System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact cc7d708bb073c44102a59ed63ce6142da1f174d1:


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 31 37 2e 30 2e 20 20  ersion 3.17.0.  
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 0a 2a 2a 20 73 69 6e 67 6c 65  o this.** single
00f0: 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68 65   large file, the
0100: 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61 6e   entire code can
0110: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73 20   be compiled as 
0120: 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c 61  a single transla
0130: 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20 54  tion.** unit.  T
0140: 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79 20  his allows many 
0150: 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f 20  compilers to do 
0160: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74 68  optimizations th
0170: 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65 0a  at would not be.
0180: 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20 74  ** possible if t
0190: 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63 6f  he files were co
01a0: 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65 6c  mpiled separatel
01b0: 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65 20  y.  Performance 
01c0: 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a 20  improvements.** 
01d0: 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61 72  of 5% or more ar
01e0: 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e 20  e commonly seen 
01f0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
0200: 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69 6e  ompiled as a sin
0210: 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74 69  gle.** translati
0220: 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20 54  on unit..**.** T
0230: 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c 20  his file is all 
0240: 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d 70  you need to comp
0250: 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f 20  ile SQLite.  To 
0260: 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f 74  use SQLite in ot
0270: 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 2c  her.** programs,
0280: 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20 66   you need this f
0290: 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71 6c  ile and the "sql
02a0: 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20 66  ite3.h" header f
02b0: 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65 73  ile that defines
02c0: 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d 6d  .** the programm
02d0: 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ing interface to
02e0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
02f0: 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64 6f  ary.  (If you do
0300: 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 74 68 65   not have.** the
0310: 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68 65 61   "sqlite3.h" hea
0320: 64 65 72 20 66 69 6c 65 20 61 74 20 68 61 6e 64  der file at hand
0330: 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e 64 20  , you will find 
0340: 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65 64 20  a copy embedded 
0350: 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 74 65  within.** the te
0360: 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c 65 2e  xt of this file.
0370: 20 20 53 65 61 72 63 68 20 66 6f 72 20 22 42 65    Search for "Be
0380: 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 33  gin file sqlite3
0390: 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68 65 20  .h" to find the 
03a0: 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65 20  start.** of the 
03b0: 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74 65 33  embedded sqlite3
03c0: 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 2e 29  .h header file.)
03d0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f 64 65   Additional code
03e0: 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 6e 65   files may be ne
03f0: 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75 20 77  eded.** if you w
0400: 61 6e 74 20 61 20 77 72 61 70 70 65 72 20 74 6f  ant a wrapper to
0410: 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c 69 74   interface SQLit
0420: 65 20 77 69 74 68 20 79 6f 75 72 20 63 68 6f 69  e with your choi
0430: 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d 69 6e  ce of programmin
0440: 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e 20 54  g.** language. T
0450: 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65 20  he code for the 
0460: 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d 61 6e  "sqlite3" comman
0470: 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69 73 20  d-line shell is 
0480: 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73 65 70  also in a.** sep
0490: 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68 69 73  arate file. This
04a0: 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 6f   file contains o
04b0: 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74 68 65  nly code for the
04c0: 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c 69 62   core SQLite lib
04d0: 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  rary..*/.#define
04e0: 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31 0a 23   SQLITE_CORE 1.#
04f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4d  define SQLITE_AM
0500: 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23 69 66  ALGAMATION 1.#if
0510: 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52 49 56  ndef SQLITE_PRIV
0520: 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ATE.# define SQL
0530: 49 54 45 5f 50 52 49 56 41 54 45 20 73 74 61 74  ITE_PRIVATE stat
0540: 69 63 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a  ic.#endif./*****
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20  ********* Begin 
0560: 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68  file sqliteInt.h
0570: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0590: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20  ********/./*.** 
05a0: 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31  2001 September 1
05b0: 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  5.**.** The auth
05c0: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70  or disclaims cop
05d0: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73  yright to this s
05e0: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20  ource code.  In 
05f0: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65  place of.** a le
0600: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65  gal notice, here
0610: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a   is a blessing:.
0620: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  **.**    May you
0630: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74   do good and not
0640: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79   evil..**    May
0650: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76   you find forgiv
0660: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65  eness for yourse
0670: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f  lf and forgive o
0680: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79  thers..**    May
0690: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c   you share freel
06a0: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20  y, never taking 
06b0: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69  more than you gi
06c0: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ve..**.*********
06d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74  .** Internal int
0720: 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f  erface definitio
0730: 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a  ns for SQLite..*
0740: 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  *.*/.#ifndef SQL
0750: 49 54 45 49 4e 54 5f 48 0a 23 64 65 66 69 6e 65  ITEINT_H.#define
0760: 20 53 51 4c 49 54 45 49 4e 54 5f 48 0a 0a 2f 2a   SQLITEINT_H../*
0770: 20 53 70 65 63 69 61 6c 20 43 6f 6d 6d 65 6e 74   Special Comment
0780: 73 3a 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 63 6f  s:.**.** Some co
0790: 6d 6d 65 6e 74 73 20 68 61 76 65 20 73 70 65 63  mments have spec
07a0: 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 74  ial meaning to t
07b0: 68 65 20 74 6f 6f 6c 73 20 74 68 61 74 20 6d 65  he tools that me
07c0: 61 73 75 72 65 20 74 65 73 74 0a 2a 2a 20 63 6f  asure test.** co
07d0: 76 65 72 61 67 65 3a 0a 2a 2a 0a 2a 2a 20 20 20  verage:.**.**   
07e0: 20 4e 4f 5f 54 45 53 54 20 20 20 20 20 20 20 20   NO_TEST        
07f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2d 20 54               - T
0800: 68 65 20 62 72 61 6e 63 68 65 73 20 6f 6e 20 74  he branches on t
0810: 68 69 73 20 6c 69 6e 65 20 61 72 65 20 6e 6f 74  his line are not
0820: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20  .**             
0830: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0840: 20 20 20 20 20 6d 65 61 73 75 72 65 64 20 62 79       measured by
0850: 20 62 72 61 6e 63 68 20 63 6f 76 65 72 61 67 65   branch coverage
0860: 2e 20 20 54 68 69 73 20 69 73 0a 2a 2a 20 20 20  .  This is.**   
0870: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 75                 u
0890: 73 65 64 20 6f 6e 20 6c 69 6e 65 73 20 6f 66 20  sed on lines of 
08a0: 63 6f 64 65 20 74 68 61 74 20 61 63 74 75 61 6c  code that actual
08b0: 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ly.**           
08c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
08d0: 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74         implement
08e0: 20 70 61 72 74 73 20 6f 66 20 63 6f 76 65 72 61   parts of covera
08f0: 67 65 20 74 65 73 74 69 6e 67 2e 0a 2a 2a 0a 2a  ge testing..**.*
0900: 2a 20 20 20 20 4f 50 54 49 4d 49 5a 41 54 49 4f  *    OPTIMIZATIO
0910: 4e 2d 49 46 2d 54 52 55 45 20 20 20 20 20 20 20  N-IF-TRUE       
0920: 20 2d 20 54 68 69 73 20 62 72 61 6e 63 68 20 69   - This branch i
0930: 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 61 6c 77  s allowed to alw
0940: 61 79 20 62 65 20 66 61 6c 73 65 0a 2a 2a 20 20  ay be false.**  
0950: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0970: 61 6e 64 20 74 68 65 20 63 6f 72 72 65 63 74 20  and the correct 
0980: 61 6e 73 77 65 72 20 69 73 20 73 74 69 6c 6c 20  answer is still 
0990: 6f 62 74 61 69 6e 65 64 2c 0a 2a 2a 20 20 20 20  obtained,.**    
09a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
09b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 74 68                th
09c0: 6f 75 67 68 20 70 65 72 68 61 70 73 20 6d 6f 72  ough perhaps mor
09d0: 65 20 73 6c 6f 77 6c 79 2e 0a 2a 2a 0a 2a 2a 20  e slowly..**.** 
09e0: 20 20 20 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 2d     OPTIMIZATION-
09f0: 49 46 2d 46 41 4c 53 45 20 20 20 20 20 20 20 2d  IF-FALSE       -
0a00: 20 54 68 69 73 20 62 72 61 6e 63 68 20 69 73 20   This branch is 
0a10: 61 6c 6c 6f 77 65 64 20 74 6f 20 61 6c 77 61 79  allowed to alway
0a20: 20 62 65 20 74 72 75 65 0a 2a 2a 20 20 20 20 20   be true.**     
0a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0a40: 20 20 20 20 20 20 20 20 20 20 20 20 20 61 6e 64               and
0a50: 20 74 68 65 20 63 6f 72 72 65 63 74 20 61 6e 73   the correct ans
0a60: 77 65 72 20 69 73 20 73 74 69 6c 6c 20 6f 62 74  wer is still obt
0a70: 61 69 6e 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20  ained,.**       
0a80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0a90: 20 20 20 20 20 20 20 20 20 20 20 74 68 6f 75 67             thoug
0aa0: 68 20 70 65 72 68 61 70 73 20 6d 6f 72 65 20 73  h perhaps more s
0ab0: 6c 6f 77 6c 79 2e 0a 2a 2a 0a 2a 2a 20 20 20 20  lowly..**.**    
0ac0: 50 52 45 56 45 4e 54 53 2d 48 41 52 4d 4c 45 53  PREVENTS-HARMLES
0ad0: 53 2d 4f 56 45 52 52 45 41 44 20 20 2d 20 54 68  S-OVERREAD  - Th
0ae0: 69 73 20 62 72 61 6e 63 68 20 70 72 65 76 65 6e  is branch preven
0af0: 74 73 20 61 20 62 75 66 66 65 72 20 6f 76 65 72  ts a buffer over
0b00: 72 65 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  read.**         
0b10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0b20: 20 20 20 20 20 20 20 20 20 74 68 61 74 20 77 6f           that wo
0b30: 75 6c 64 20 62 65 20 68 61 72 6d 6c 65 73 73 20  uld be harmless 
0b40: 61 6e 64 20 75 6e 64 65 74 65 63 74 61 62 6c 65  and undetectable
0b50: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20  .**             
0b60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0b70: 20 20 20 20 20 69 66 20 69 74 20 64 69 64 20 6f       if it did o
0b80: 63 63 75 72 2e 20 20 0a 2a 2a 0a 2a 2a 20 49 6e  ccur.  .**.** In
0b90: 20 61 6c 6c 20 63 61 73 65 73 2c 20 74 68 65 20   all cases, the 
0ba0: 73 70 65 63 69 61 6c 20 63 6f 6d 6d 65 6e 74 20  special comment 
0bb0: 6d 75 73 74 20 62 65 20 65 6e 63 6c 6f 73 65 64  must be enclosed
0bc0: 20 69 6e 20 74 68 65 20 75 73 75 61 6c 0a 2a 2a   in the usual.**
0bd0: 20 73 6c 61 73 68 2d 61 73 74 65 72 69 73 6b 2e   slash-asterisk.
0be0: 2e 2e 61 73 74 65 72 69 73 6b 2d 73 6c 61 73 68  ..asterisk-slash
0bf0: 20 63 6f 6d 6d 65 6e 74 20 6d 61 72 6b 73 2c 20   comment marks, 
0c00: 77 69 74 68 20 6e 6f 20 73 70 61 63 65 73 20 62  with no spaces b
0c10: 65 74 77 65 65 6e 20 74 68 65 20 0a 2a 2a 20 61  etween the .** a
0c20: 73 74 65 72 69 73 6b 73 20 61 6e 64 20 74 68 65  sterisks and the
0c30: 20 63 6f 6d 6d 65 6e 74 20 74 65 78 74 2e 0a 2a   comment text..*
0c40: 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75  /../*.** Make su
0c50: 72 65 20 74 68 65 20 54 63 6c 20 63 61 6c 6c 69  re the Tcl calli
0c60: 6e 67 20 63 6f 6e 76 65 6e 74 69 6f 6e 20 6d 61  ng convention ma
0c70: 63 72 6f 20 69 73 20 64 65 66 69 6e 65 64 2e 20  cro is defined. 
0c80: 20 54 68 69 73 20 6d 61 63 72 6f 20 69 73 0a 2a   This macro is.*
0c90: 2a 20 6f 6e 6c 79 20 75 73 65 64 20 62 79 20 74  * only used by t
0ca0: 65 73 74 20 63 6f 64 65 20 61 6e 64 20 54 63 6c  est code and Tcl
0cb0: 20 69 6e 74 65 67 72 61 74 69 6f 6e 20 63 6f 64   integration cod
0cc0: 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  e..*/.#ifndef SQ
0cd0: 4c 49 54 45 5f 54 43 4c 41 50 49 0a 23 20 20 64  LITE_TCLAPI.#  d
0ce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 43 4c  efine SQLITE_TCL
0cf0: 41 50 49 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  API.#endif../*.*
0d00: 2a 20 4d 61 6b 65 20 73 75 72 65 20 74 68 61 74  * Make sure that
0d10: 20 72 61 6e 64 5f 73 28 29 20 69 73 20 61 76 61   rand_s() is ava
0d20: 69 6c 61 62 6c 65 20 6f 6e 20 57 69 6e 64 6f 77  ilable on Window
0d30: 73 20 73 79 73 74 65 6d 73 20 77 69 74 68 20 4d  s systems with M
0d40: 53 56 43 20 32 30 30 35 0a 2a 2a 20 6f 72 20 68  SVC 2005.** or h
0d50: 69 67 68 65 72 2e 0a 2a 2f 0a 23 69 66 20 64 65  igher..*/.#if de
0d60: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20  fined(_MSC_VER) 
0d70: 26 26 20 5f 4d 53 43 5f 56 45 52 3e 3d 31 34 30  && _MSC_VER>=140
0d80: 30 0a 23 20 20 64 65 66 69 6e 65 20 5f 43 52 54  0.#  define _CRT
0d90: 5f 52 41 4e 44 5f 53 0a 23 65 6e 64 69 66 0a 0a  _RAND_S.#endif..
0da0: 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68  /*.** Include th
0db0: 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 75 73  e header file us
0dc0: 65 64 20 74 6f 20 63 75 73 74 6f 6d 69 7a 65 20  ed to customize 
0dd0: 74 68 65 20 63 6f 6d 70 69 6c 65 72 20 6f 70 74  the compiler opt
0de0: 69 6f 6e 73 20 66 6f 72 20 4d 53 56 43 2e 0a 2a  ions for MSVC..*
0df0: 2a 20 54 68 69 73 20 73 68 6f 75 6c 64 20 62 65  * This should be
0e00: 20 64 6f 6e 65 20 66 69 72 73 74 20 73 6f 20 74   done first so t
0e10: 68 61 74 20 69 74 20 63 61 6e 20 73 75 63 63 65  hat it can succe
0e20: 73 73 66 75 6c 6c 79 20 70 72 65 76 65 6e 74 20  ssfully prevent 
0e30: 73 70 75 72 69 6f 75 73 0a 2a 2a 20 63 6f 6d 70  spurious.** comp
0e40: 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 20 64 75  iler warnings du
0e50: 65 20 74 6f 20 73 75 62 73 65 71 75 65 6e 74 20  e to subsequent 
0e60: 63 6f 6e 74 65 6e 74 20 69 6e 20 74 68 69 73 20  content in this 
0e70: 66 69 6c 65 20 61 6e 64 20 6f 74 68 65 72 20 66  file and other f
0e80: 69 6c 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  iles.** that are
0e90: 20 69 6e 63 6c 75 64 65 64 20 62 79 20 74 68 69   included by thi
0ea0: 73 20 66 69 6c 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  s file..*/./****
0eb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75  ********** Inclu
0ec0: 64 65 20 6d 73 76 63 2e 68 20 69 6e 20 74 68 65  de msvc.h in the
0ed0: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74   middle of sqlit
0ee0: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
0ef0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a  *********/./****
0f00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e  ********** Begin
0f10: 20 66 69 6c 65 20 6d 73 76 63 2e 68 20 2a 2a 2a   file msvc.h ***
0f20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0f30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0f40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a  *********/./*.**
0f50: 20 32 30 31 35 20 4a 61 6e 75 61 72 79 20 31 32   2015 January 12
0f60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0f70: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0f80: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0f90: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0fa0: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0fb0: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0fc0: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0fd0: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0fe0: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
0ff0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
1000: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
1010: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
1020: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
1030: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
1040: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
1050: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
1060: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
1070: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
1080: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1090: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
10a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
10b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
10c0: 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ****.**.** This 
10d0: 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 63 6f  file contains co
10e0: 64 65 20 74 68 61 74 20 69 73 20 73 70 65 63 69  de that is speci
10f0: 66 69 63 20 74 6f 20 4d 53 56 43 2e 0a 2a 2f 0a  fic to MSVC..*/.
1100: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  #ifndef SQLITE_M
1110: 53 56 43 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  SVC_H.#define SQ
1120: 4c 49 54 45 5f 4d 53 56 43 5f 48 0a 0a 23 69 66  LITE_MSVC_H..#if
1130: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45   defined(_MSC_VE
1140: 52 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  R).#pragma warni
1150: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 30 35  ng(disable : 405
1160: 34 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  4).#pragma warni
1170: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 30 35  ng(disable : 405
1180: 35 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  5).#pragma warni
1190: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 30  ng(disable : 410
11a0: 30 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  0).#pragma warni
11b0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 32  ng(disable : 412
11c0: 37 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  7).#pragma warni
11d0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 33  ng(disable : 413
11e0: 30 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  0).#pragma warni
11f0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 35  ng(disable : 415
1200: 32 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  2).#pragma warni
1210: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 38  ng(disable : 418
1220: 39 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  9).#pragma warni
1230: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 30  ng(disable : 420
1240: 36 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  6).#pragma warni
1250: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 31  ng(disable : 421
1260: 30 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  0).#pragma warni
1270: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 33  ng(disable : 423
1280: 32 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  2).#pragma warni
1290: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 34  ng(disable : 424
12a0: 34 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  4).#pragma warni
12b0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 33 30  ng(disable : 430
12c0: 35 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  5).#pragma warni
12d0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 33 30  ng(disable : 430
12e0: 36 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  6).#pragma warni
12f0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 37 30  ng(disable : 470
1300: 32 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  2).#pragma warni
1310: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 37 30  ng(disable : 470
1320: 36 29 0a 23 65 6e 64 69 66 20 2f 2a 20 64 65 66  6).#endif /* def
1330: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 2a  ined(_MSC_VER) *
1340: 2f 0a 0a 23 65 6e 64 69 66 20 2f 2a 20 53 51 4c  /..#endif /* SQL
1350: 49 54 45 5f 4d 53 56 43 5f 48 20 2a 2f 0a 0a 2f  ITE_MSVC_H */../
1360: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45  ************** E
1370: 6e 64 20 6f 66 20 6d 73 76 63 2e 68 20 2a 2a 2a  nd of msvc.h ***
1380: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1390: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
13b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43  ************** C
13c0: 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72 65 20  ontinuing where 
13d0: 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e 20 73  we left off in s
13e0: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a  qliteInt.h *****
13f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a  *************/..
1400: 2f 2a 0a 2a 2a 20 53 70 65 63 69 61 6c 20 73 65  /*.** Special se
1410: 74 75 70 20 66 6f 72 20 56 78 57 6f 72 6b 73 0a  tup for VxWorks.
1420: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
1430: 2a 2a 20 49 6e 63 6c 75 64 65 20 76 78 77 6f 72  ** Include vxwor
1440: 6b 73 2e 68 20 69 6e 20 74 68 65 20 6d 69 64 64  ks.h in the midd
1450: 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 6e 74 2e  le of sqliteInt.
1460: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  h **************
1470: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
1480: 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 76 78  ** Begin file vx
1490: 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a  works.h ********
14a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
14b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
14c0: 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 31 35 2d 30 33  */./*.** 2015-03
14d0: 2d 30 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  -02.**.** The au
14e0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
14f0: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
1500: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
1510: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
1520: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
1530: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
1540: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
1550: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
1560: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
1570: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
1580: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
1590: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
15a0: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
15b0: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
15c0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
15d0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
15e0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
15f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1600: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1630: 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68  *******.**.** Th
1640: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
1650: 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 73 70   code that is sp
1660: 65 63 69 66 69 63 20 74 6f 20 57 69 6e 64 20 52  ecific to Wind R
1670: 69 76 65 72 27 73 20 56 78 57 6f 72 6b 73 0a 2a  iver's VxWorks.*
1680: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f  /.#if defined(__
1690: 52 54 50 5f 5f 29 20 7c 7c 20 64 65 66 69 6e 65  RTP__) || define
16a0: 64 28 5f 57 52 53 5f 4b 45 52 4e 45 4c 29 0a 2f  d(_WRS_KERNEL)./
16b0: 2a 20 54 68 69 73 20 69 73 20 56 78 57 6f 72 6b  * This is VxWork
16c0: 73 2e 20 20 53 65 74 20 75 70 20 74 68 69 6e 67  s.  Set up thing
16d0: 73 20 73 70 65 63 69 61 6c 6c 79 20 66 6f 72 20  s specially for 
16e0: 74 68 61 74 20 4f 53 0a 2a 2f 0a 23 69 6e 63 6c  that OS.*/.#incl
16f0: 75 64 65 20 3c 76 78 57 6f 72 6b 73 2e 68 3e 0a  ude <vxWorks.h>.
1700: 23 69 6e 63 6c 75 64 65 20 3c 70 74 68 72 65 61  #include <pthrea
1710: 64 2e 68 3e 20 20 2f 2a 20 61 6d 61 6c 67 61 6d  d.h>  /* amalgam
1720: 61 74 6f 72 3a 20 64 6f 6e 74 63 61 63 68 65 20  ator: dontcache 
1730: 2a 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f 56 58  */.#define OS_VX
1740: 57 4f 52 4b 53 20 31 0a 23 64 65 66 69 6e 65 20  WORKS 1.#define 
1750: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 20  SQLITE_OS_OTHER 
1760: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
1770: 5f 48 4f 4d 45 47 52 4f 57 4e 5f 52 45 43 55 52  _HOMEGROWN_RECUR
1780: 53 49 56 45 5f 4d 55 54 45 58 20 31 0a 23 64 65  SIVE_MUTEX 1.#de
1790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fine SQLITE_OMIT
17a0: 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20  _LOAD_EXTENSION 
17b0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
17c0: 5f 45 4e 41 42 4c 45 5f 4c 4f 43 4b 49 4e 47 5f  _ENABLE_LOCKING_
17d0: 53 54 59 4c 45 20 30 0a 23 64 65 66 69 6e 65 20  STYLE 0.#define 
17e0: 48 41 56 45 5f 55 54 49 4d 45 20 31 0a 23 65 6c  HAVE_UTIME 1.#el
17f0: 73 65 0a 2f 2a 20 54 68 69 73 20 69 73 20 6e 6f  se./* This is no
1800: 74 20 56 78 57 6f 72 6b 73 2e 20 2a 2f 0a 23 64  t VxWorks. */.#d
1810: 65 66 69 6e 65 20 4f 53 5f 56 58 57 4f 52 4b 53  efine OS_VXWORKS
1820: 20 30 0a 23 64 65 66 69 6e 65 20 48 41 56 45 5f   0.#define HAVE_
1830: 46 43 48 4f 57 4e 20 31 0a 23 64 65 66 69 6e 65  FCHOWN 1.#define
1840: 20 48 41 56 45 5f 52 45 41 44 4c 49 4e 4b 20 31   HAVE_READLINK 1
1850: 0a 23 64 65 66 69 6e 65 20 48 41 56 45 5f 4c 53  .#define HAVE_LS
1860: 54 41 54 20 31 0a 23 65 6e 64 69 66 20 2f 2a 20  TAT 1.#endif /* 
1870: 64 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 52  defined(_WRS_KER
1880: 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a  NEL) */../******
1890: 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 20 6f 66 20  ******** End of 
18a0: 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a 2a 2a  vxworks.h ******
18b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18d0: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  *******/./******
18e0: 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e 74 69 6e 75  ******** Continu
18f0: 69 6e 67 20 77 68 65 72 65 20 77 65 20 6c 65 66  ing where we lef
1900: 74 20 6f 66 66 20 69 6e 20 73 71 6c 69 74 65 49  t off in sqliteI
1910: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  nt.h ***********
1920: 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  *******/../*.** 
1930: 54 68 65 73 65 20 23 64 65 66 69 6e 65 73 20 73  These #defines s
1940: 68 6f 75 6c 64 20 65 6e 61 62 6c 65 20 3e 32 47  hould enable >2G
1950: 42 20 66 69 6c 65 20 73 75 70 70 6f 72 74 20 6f  B file support o
1960: 6e 20 50 4f 53 49 58 20 69 66 20 74 68 65 0a 2a  n POSIX if the.*
1970: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  * underlying ope
1980: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 73 75  rating system su
1990: 70 70 6f 72 74 73 20 69 74 2e 20 20 49 66 20 74  pports it.  If t
19a0: 68 65 20 4f 53 20 6c 61 63 6b 73 0a 2a 2a 20 6c  he OS lacks.** l
19b0: 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72  arge file suppor
19c0: 74 2c 20 6f 72 20 69 66 20 74 68 65 20 4f 53 20  t, or if the OS 
19d0: 69 73 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 73  is windows, thes
19e0: 65 20 73 68 6f 75 6c 64 20 62 65 20 6e 6f 2d 6f  e should be no-o
19f0: 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 69 63 6b 65 74  ps..**.** Ticket
1a00: 20 23 32 37 33 39 3a 20 20 54 68 65 20 5f 4c 41   #2739:  The _LA
1a10: 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 20 6d  RGEFILE_SOURCE m
1a20: 61 63 72 6f 20 6d 75 73 74 20 61 70 70 65 61 72  acro must appear
1a30: 20 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a 20 73   before any.** s
1a40: 79 73 74 65 6d 20 23 69 6e 63 6c 75 64 65 73 2e  ystem #includes.
1a50: 20 20 48 65 6e 63 65 2c 20 74 68 69 73 20 62 6c    Hence, this bl
1a60: 6f 63 6b 20 6f 66 20 63 6f 64 65 20 6d 75 73 74  ock of code must
1a70: 20 62 65 20 74 68 65 20 76 65 72 79 20 66 69 72   be the very fir
1a80: 73 74 0a 2a 2a 20 63 6f 64 65 20 69 6e 20 61 6c  st.** code in al
1a90: 6c 20 73 6f 75 72 63 65 20 66 69 6c 65 73 2e 0a  l source files..
1aa0: 2a 2a 0a 2a 2a 20 4c 61 72 67 65 20 66 69 6c 65  **.** Large file
1ab0: 20 73 75 70 70 6f 72 74 20 63 61 6e 20 62 65 20   support can be 
1ac0: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 74  disabled using t
1ad0: 68 65 20 2d 44 53 51 4c 49 54 45 5f 44 49 53 41  he -DSQLITE_DISA
1ae0: 42 4c 45 5f 4c 46 53 20 73 77 69 74 63 68 0a 2a  BLE_LFS switch.*
1af0: 2a 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  * on the compile
1b00: 72 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65 2e 20  r command line. 
1b10: 20 54 68 69 73 20 69 73 20 6e 65 63 65 73 73 61   This is necessa
1b20: 72 79 20 69 66 20 79 6f 75 20 61 72 65 20 63 6f  ry if you are co
1b30: 6d 70 69 6c 69 6e 67 0a 2a 2a 20 6f 6e 20 61 20  mpiling.** on a 
1b40: 72 65 63 65 6e 74 20 6d 61 63 68 69 6e 65 20 28  recent machine (
1b50: 65 78 3a 20 52 65 64 20 48 61 74 20 37 2e 32 29  ex: Red Hat 7.2)
1b60: 20 62 75 74 20 79 6f 75 20 77 61 6e 74 20 79 6f   but you want yo
1b70: 75 72 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  ur code to work.
1b80: 2a 2a 20 6f 6e 20 61 6e 20 6f 6c 64 65 72 20 6d  ** on an older m
1b90: 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20  achine (ex: Red 
1ba0: 48 61 74 20 36 2e 30 29 2e 20 20 49 66 20 79 6f  Hat 6.0).  If yo
1bb0: 75 20 63 6f 6d 70 69 6c 65 20 6f 6e 20 52 65 64  u compile on Red
1bc0: 20 48 61 74 20 37 2e 32 0a 2a 2a 20 77 69 74 68   Hat 7.2.** with
1bd0: 6f 75 74 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c  out this option,
1be0: 20 4c 46 53 20 69 73 20 65 6e 61 62 6c 65 2e 20   LFS is enable. 
1bf0: 20 42 75 74 20 4c 46 53 20 64 6f 65 73 20 6e 6f   But LFS does no
1c00: 74 20 65 78 69 73 74 20 69 6e 20 74 68 65 20 6b  t exist in the k
1c10: 65 72 6e 65 6c 0a 2a 2a 20 69 6e 20 52 65 64 20  ernel.** in Red 
1c20: 48 61 74 20 36 2e 30 2c 20 73 6f 20 74 68 65 20  Hat 6.0, so the 
1c30: 63 6f 64 65 20 77 6f 6e 27 74 20 77 6f 72 6b 2e  code won't work.
1c40: 20 20 48 65 6e 63 65 2c 20 66 6f 72 20 6d 61 78    Hence, for max
1c50: 69 6d 75 6d 20 62 69 6e 61 72 79 0a 2a 2a 20 70  imum binary.** p
1c60: 6f 72 74 61 62 69 6c 69 74 79 20 79 6f 75 20 73  ortability you s
1c70: 68 6f 75 6c 64 20 6f 6d 69 74 20 4c 46 53 2e 0a  hould omit LFS..
1c80: 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 76 69 6f  **.** The previo
1c90: 75 73 20 70 61 72 61 67 72 61 70 68 20 77 61 73  us paragraph was
1ca0: 20 77 72 69 74 74 65 6e 20 69 6e 20 32 30 30 35   written in 2005
1cb0: 2e 20 20 28 54 68 69 73 20 70 61 72 61 67 72 61  .  (This paragra
1cc0: 70 68 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  ph is written.**
1cd0: 20 6f 6e 20 32 30 30 38 2d 31 31 2d 32 38 2e 29   on 2008-11-28.)
1ce0: 20 54 68 65 73 65 20 64 61 79 73 2c 20 61 6c 6c   These days, all
1cf0: 20 4c 69 6e 75 78 20 6b 65 72 6e 65 6c 73 20 73   Linux kernels s
1d00: 75 70 70 6f 72 74 20 6c 61 72 67 65 20 66 69 6c  upport large fil
1d10: 65 73 2c 20 73 6f 0a 2a 2a 20 79 6f 75 20 73 68  es, so.** you sh
1d20: 6f 75 6c 64 20 70 72 6f 62 61 62 6c 79 20 6c 65  ould probably le
1d30: 61 76 65 20 4c 46 53 20 65 6e 61 62 6c 65 64 2e  ave LFS enabled.
1d40: 20 20 42 75 74 20 73 6f 6d 65 20 65 6d 62 65 64    But some embed
1d50: 64 65 64 20 70 6c 61 74 66 6f 72 6d 73 20 6d 69  ded platforms mi
1d60: 67 68 74 0a 2a 2a 20 6c 61 63 6b 20 4c 46 53 20  ght.** lack LFS 
1d70: 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
1d80: 65 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45  e SQLITE_DISABLE
1d90: 5f 4c 46 53 20 6d 61 63 72 6f 20 6d 69 67 68 74  _LFS macro might
1da0: 20 73 74 69 6c 6c 20 62 65 20 75 73 65 66 75 6c   still be useful
1db0: 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d 69 6c 61 72 20  ..**.** Similar 
1dc0: 69 73 20 74 72 75 65 20 66 6f 72 20 4d 61 63 20  is true for Mac 
1dd0: 4f 53 20 58 2e 20 20 4c 46 53 20 69 73 20 6f 6e  OS X.  LFS is on
1de0: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20  ly supported on 
1df0: 4d 61 63 20 4f 53 20 58 20 39 20 61 6e 64 20 6c  Mac OS X 9 and l
1e00: 61 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  ater..*/.#ifndef
1e10: 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f   SQLITE_DISABLE_
1e20: 4c 46 53 0a 23 20 64 65 66 69 6e 65 20 5f 4c 41  LFS.# define _LA
1e30: 52 47 45 5f 46 49 4c 45 20 20 20 20 20 20 20 31  RGE_FILE       1
1e40: 0a 23 20 69 66 6e 64 65 66 20 5f 46 49 4c 45 5f  .# ifndef _FILE_
1e50: 4f 46 46 53 45 54 5f 42 49 54 53 0a 23 20 20 20  OFFSET_BITS.#   
1e60: 64 65 66 69 6e 65 20 5f 46 49 4c 45 5f 4f 46 46  define _FILE_OFF
1e70: 53 45 54 5f 42 49 54 53 20 36 34 0a 23 20 65 6e  SET_BITS 64.# en
1e80: 64 69 66 0a 23 20 64 65 66 69 6e 65 20 5f 4c 41  dif.# define _LA
1e90: 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 20 31  RGEFILE_SOURCE 1
1ea0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 54 68 65 20  .#endif../* The 
1eb0: 47 43 43 5f 56 45 52 53 49 4f 4e 2c 20 43 4c 41  GCC_VERSION, CLA
1ec0: 4e 47 5f 56 45 52 53 49 4f 4e 2c 20 61 6e 64 20  NG_VERSION, and 
1ed0: 4d 53 56 43 5f 56 45 52 53 49 4f 4e 20 6d 61 63  MSVC_VERSION mac
1ee0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  ros are used to.
1ef0: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79  ** conditionally
1f00: 20 69 6e 63 6c 75 64 65 20 6f 70 74 69 6d 69 7a   include optimiz
1f10: 61 74 69 6f 6e 73 20 66 6f 72 20 65 61 63 68 20  ations for each 
1f20: 6f 66 20 74 68 65 73 65 20 63 6f 6d 70 69 6c 65  of these compile
1f30: 72 73 2e 20 20 41 0a 2a 2a 20 76 61 6c 75 65 20  rs.  A.** value 
1f40: 6f 66 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20  of 0 means that 
1f50: 63 6f 6d 70 69 6c 65 72 20 69 73 20 6e 6f 74 20  compiler is not 
1f60: 62 65 69 6e 67 20 75 73 65 64 2e 20 20 54 68 65  being used.  The
1f70: 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 49 53 41 42  .** SQLITE_DISAB
1f80: 4c 45 5f 49 4e 54 52 49 4e 53 49 43 20 6d 61 63  LE_INTRINSIC mac
1f90: 72 6f 20 6d 65 61 6e 73 20 64 6f 20 6e 6f 74 20  ro means do not 
1fa0: 75 73 65 20 61 6e 79 20 63 6f 6d 70 69 6c 65 72  use any compiler
1fb0: 2d 73 70 65 63 69 66 69 63 0a 2a 2a 20 6f 70 74  -specific.** opt
1fc0: 69 6d 69 7a 61 74 69 6f 6e 73 2c 20 61 6e 64 20  imizations, and 
1fd0: 68 65 6e 63 65 20 73 65 74 20 61 6c 6c 20 63 6f  hence set all co
1fe0: 6d 70 69 6c 65 72 20 6d 61 63 72 6f 73 20 74 6f  mpiler macros to
1ff0: 20 30 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65   0.*/.#if define
2000: 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 26 26 20 21  d(__GNUC__) && !
2010: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44  defined(SQLITE_D
2020: 49 53 41 42 4c 45 5f 49 4e 54 52 49 4e 53 49 43  ISABLE_INTRINSIC
2030: 29 0a 23 20 64 65 66 69 6e 65 20 47 43 43 5f 56  ).# define GCC_V
2040: 45 52 53 49 4f 4e 20 28 5f 5f 47 4e 55 43 5f 5f  ERSION (__GNUC__
2050: 2a 31 30 30 30 30 30 30 2b 5f 5f 47 4e 55 43 5f  *1000000+__GNUC_
2060: 4d 49 4e 4f 52 5f 5f 2a 31 30 30 30 2b 5f 5f 47  MINOR__*1000+__G
2070: 4e 55 43 5f 50 41 54 43 48 4c 45 56 45 4c 5f 5f  NUC_PATCHLEVEL__
2080: 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  ).#else.# define
2090: 20 47 43 43 5f 56 45 52 53 49 4f 4e 20 30 0a 23   GCC_VERSION 0.#
20a0: 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69 6e 65  endif.#if define
20b0: 64 28 5f 5f 63 6c 61 6e 67 5f 5f 29 20 26 26 20  d(__clang__) && 
20c0: 21 64 65 66 69 6e 65 64 28 5f 57 49 4e 33 32 29  !defined(_WIN32)
20d0: 20 26 26 20 21 64 65 66 69 6e 65 64 28 53 51 4c   && !defined(SQL
20e0: 49 54 45 5f 44 49 53 41 42 4c 45 5f 49 4e 54 52  ITE_DISABLE_INTR
20f0: 49 4e 53 49 43 29 0a 23 20 64 65 66 69 6e 65 20  INSIC).# define 
2100: 43 4c 41 4e 47 5f 56 45 52 53 49 4f 4e 20 5c 0a  CLANG_VERSION \.
2110: 20 20 20 20 20 20 20 20 20 20 20 20 28 5f 5f 63              (__c
2120: 6c 61 6e 67 5f 6d 61 6a 6f 72 5f 5f 2a 31 30 30  lang_major__*100
2130: 30 30 30 30 2b 5f 5f 63 6c 61 6e 67 5f 6d 69 6e  0000+__clang_min
2140: 6f 72 5f 5f 2a 31 30 30 30 2b 5f 5f 63 6c 61 6e  or__*1000+__clan
2150: 67 5f 70 61 74 63 68 6c 65 76 65 6c 5f 5f 29 0a  g_patchlevel__).
2160: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 43  #else.# define C
2170: 4c 41 4e 47 5f 56 45 52 53 49 4f 4e 20 30 0a 23  LANG_VERSION 0.#
2180: 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69 6e 65  endif.#if define
2190: 64 28 5f 4d 53 43 5f 56 45 52 29 20 26 26 20 21  d(_MSC_VER) && !
21a0: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44  defined(SQLITE_D
21b0: 49 53 41 42 4c 45 5f 49 4e 54 52 49 4e 53 49 43  ISABLE_INTRINSIC
21c0: 29 0a 23 20 64 65 66 69 6e 65 20 4d 53 56 43 5f  ).# define MSVC_
21d0: 56 45 52 53 49 4f 4e 20 5f 4d 53 43 5f 56 45 52  VERSION _MSC_VER
21e0: 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
21f0: 4d 53 56 43 5f 56 45 52 53 49 4f 4e 20 30 0a 23  MSVC_VERSION 0.#
2200: 65 6e 64 69 66 0a 0a 2f 2a 20 4e 65 65 64 65 64  endif../* Needed
2210: 20 66 6f 72 20 76 61 72 69 6f 75 73 20 64 65 66   for various def
2220: 69 6e 69 74 69 6f 6e 73 2e 2e 2e 20 2a 2f 0a 23  initions... */.#
2230: 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e 55  if defined(__GNU
2240: 43 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64  C__) && !defined
2250: 28 5f 47 4e 55 5f 53 4f 55 52 43 45 29 0a 23 20  (_GNU_SOURCE).# 
2260: 64 65 66 69 6e 65 20 5f 47 4e 55 5f 53 4f 55 52  define _GNU_SOUR
2270: 43 45 0a 23 65 6e 64 69 66 0a 0a 23 69 66 20 64  CE.#endif..#if d
2280: 65 66 69 6e 65 64 28 5f 5f 4f 70 65 6e 42 53 44  efined(__OpenBSD
2290: 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64 28  __) && !defined(
22a0: 5f 42 53 44 5f 53 4f 55 52 43 45 29 0a 23 20 64  _BSD_SOURCE).# d
22b0: 65 66 69 6e 65 20 5f 42 53 44 5f 53 4f 55 52 43  efine _BSD_SOURC
22c0: 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  E.#endif../*.** 
22d0: 46 6f 72 20 4d 69 6e 47 57 2c 20 63 68 65 63 6b  For MinGW, check
22e0: 20 74 6f 20 73 65 65 20 69 66 20 77 65 20 63 61   to see if we ca
22f0: 6e 20 69 6e 63 6c 75 64 65 20 74 68 65 20 68 65  n include the he
2300: 61 64 65 72 20 66 69 6c 65 20 63 6f 6e 74 61 69  ader file contai
2310: 6e 69 6e 67 20 69 74 73 0a 2a 2a 20 76 65 72 73  ning its.** vers
2320: 69 6f 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c  ion information,
2330: 20 61 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   among other thi
2340: 6e 67 73 2e 20 20 4e 6f 72 6d 61 6c 6c 79 2c 20  ngs.  Normally, 
2350: 74 68 69 73 20 69 6e 74 65 72 6e 61 6c 20 4d 69  this internal Mi
2360: 6e 47 57 0a 2a 2a 20 68 65 61 64 65 72 20 66 69  nGW.** header fi
2370: 6c 65 20 77 6f 75 6c 64 20 5b 6f 6e 6c 79 5d 20  le would [only] 
2380: 62 65 20 69 6e 63 6c 75 64 65 64 20 61 75 74 6f  be included auto
2390: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 6f 74 68  matically by oth
23a0: 65 72 20 4d 69 6e 47 57 20 68 65 61 64 65 72 0a  er MinGW header.
23b0: 2a 2a 20 66 69 6c 65 73 3b 20 68 6f 77 65 76 65  ** files; howeve
23c0: 72 2c 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 64  r, the contained
23d0: 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d 61   version informa
23e0: 74 69 6f 6e 20 69 73 20 6e 6f 77 20 72 65 71 75  tion is now requ
23f0: 69 72 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  ired by this.** 
2400: 68 65 61 64 65 72 20 66 69 6c 65 20 74 6f 20 77  header file to w
2410: 6f 72 6b 20 61 72 6f 75 6e 64 20 62 69 6e 61 72  ork around binar
2420: 79 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  y compatibility 
2430: 69 73 73 75 65 73 20 28 73 65 65 20 62 65 6c 6f  issues (see belo
2440: 77 29 20 61 6e 64 0a 2a 2a 20 74 68 69 73 20 69  w) and.** this i
2450: 73 20 74 68 65 20 6f 6e 6c 79 20 6b 6e 6f 77 6e  s the only known
2460: 20 77 61 79 20 74 6f 20 72 65 6c 69 61 62 6c 79   way to reliably
2470: 20 6f 62 74 61 69 6e 20 69 74 2e 20 20 54 68 69   obtain it.  Thi
2480: 73 20 65 6e 74 69 72 65 20 23 69 66 20 62 6c 6f  s entire #if blo
2490: 63 6b 0a 2a 2a 20 77 6f 75 6c 64 20 62 65 20 63  ck.** would be c
24a0: 6f 6d 70 6c 65 74 65 6c 79 20 75 6e 6e 65 63 65  ompletely unnece
24b0: 73 73 61 72 79 20 69 66 20 74 68 65 72 65 20 77  ssary if there w
24c0: 61 73 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  as any other way
24d0: 20 6f 66 20 64 65 74 65 63 74 69 6e 67 0a 2a 2a   of detecting.**
24e0: 20 4d 69 6e 47 57 20 76 69 61 20 74 68 65 69 72   MinGW via their
24f0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 28 65   preprocessor (e
2500: 2e 67 2e 20 69 66 20 74 68 65 79 20 63 75 73 74  .g. if they cust
2510: 6f 6d 69 7a 65 64 20 74 68 65 69 72 20 47 43 43  omized their GCC
2520: 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 73 6f   to define.** so
2530: 6d 65 20 4d 69 6e 47 57 2d 73 70 65 63 69 66 69  me MinGW-specifi
2540: 63 20 6d 61 63 72 6f 73 29 2e 20 20 57 68 65 6e  c macros).  When
2550: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 4d   compiling for M
2560: 69 6e 47 57 2c 20 65 69 74 68 65 72 20 74 68 65  inGW, either the
2570: 0a 2a 2a 20 5f 48 41 56 45 5f 4d 49 4e 47 57 5f  .** _HAVE_MINGW_
2580: 48 20 6f 72 20 5f 48 41 56 45 5f 5f 4d 49 4e 47  H or _HAVE__MING
2590: 57 5f 48 20 28 6e 6f 74 65 20 74 68 65 20 65 78  W_H (note the ex
25a0: 74 72 61 20 75 6e 64 65 72 73 63 6f 72 65 29 20  tra underscore) 
25b0: 6d 61 63 72 6f 20 6d 75 73 74 20 62 65 0a 2a 2a  macro must be.**
25c0: 20 64 65 66 69 6e 65 64 3b 20 6f 74 68 65 72 77   defined; otherw
25d0: 69 73 65 2c 20 64 65 74 65 63 74 69 6f 6e 20 6f  ise, detection o
25e0: 66 20 63 6f 6e 64 69 74 69 6f 6e 73 20 73 70 65  f conditions spe
25f0: 63 69 66 69 63 20 74 6f 20 4d 69 6e 47 57 20 77  cific to MinGW w
2600: 69 6c 6c 20 62 65 0a 2a 2a 20 64 69 73 61 62 6c  ill be.** disabl
2610: 65 64 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e  ed..*/.#if defin
2620: 65 64 28 5f 48 41 56 45 5f 4d 49 4e 47 57 5f 48  ed(_HAVE_MINGW_H
2630: 29 0a 23 20 69 6e 63 6c 75 64 65 20 22 6d 69 6e  ).# include "min
2640: 67 77 2e 68 22 0a 23 65 6c 69 66 20 64 65 66 69  gw.h".#elif defi
2650: 6e 65 64 28 5f 48 41 56 45 5f 5f 4d 49 4e 47 57  ned(_HAVE__MINGW
2660: 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 22 5f  _H).# include "_
2670: 6d 69 6e 67 77 2e 68 22 0a 23 65 6e 64 69 66 0a  mingw.h".#endif.
2680: 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47 57  ./*.** For MinGW
2690: 20 76 65 72 73 69 6f 6e 20 34 2e 78 20 28 61 6e   version 4.x (an
26a0: 64 20 68 69 67 68 65 72 29 2c 20 63 68 65 63 6b  d higher), check
26b0: 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 20 5f   to see if the _
26c0: 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f 54  USE_32BIT_TIME_T
26d0: 0a 2a 2a 20 64 65 66 69 6e 65 20 69 73 20 72 65  .** define is re
26e0: 71 75 69 72 65 64 20 74 6f 20 6d 61 69 6e 74 61  quired to mainta
26f0: 69 6e 20 62 69 6e 61 72 79 20 63 6f 6d 70 61 74  in binary compat
2700: 69 62 69 6c 69 74 79 20 77 69 74 68 20 74 68 65  ibility with the
2710: 20 4d 53 56 43 20 72 75 6e 74 69 6d 65 0a 2a 2a   MSVC runtime.**
2720: 20 6c 69 62 72 61 72 79 20 69 6e 20 75 73 65 20   library in use 
2730: 28 65 2e 67 2e 20 66 6f 72 20 57 69 6e 64 6f 77  (e.g. for Window
2740: 73 20 58 50 29 2e 0a 2a 2f 0a 23 69 66 20 21 64  s XP)..*/.#if !d
2750: 65 66 69 6e 65 64 28 5f 55 53 45 5f 33 32 42 49  efined(_USE_32BI
2760: 54 5f 54 49 4d 45 5f 54 29 20 26 26 20 21 64 65  T_TIME_T) && !de
2770: 66 69 6e 65 64 28 5f 55 53 45 5f 36 34 42 49 54  fined(_USE_64BIT
2780: 5f 54 49 4d 45 5f 54 29 20 26 26 20 5c 0a 20 20  _TIME_T) && \.  
2790: 20 20 64 65 66 69 6e 65 64 28 5f 57 49 4e 33 32    defined(_WIN32
27a0: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 57  ) && !defined(_W
27b0: 49 4e 36 34 29 20 26 26 20 5c 0a 20 20 20 20 64  IN64) && \.    d
27c0: 65 66 69 6e 65 64 28 5f 5f 4d 49 4e 47 57 5f 4d  efined(__MINGW_M
27d0: 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 29 20 26 26  AJOR_VERSION) &&
27e0: 20 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f 56   __MINGW_MAJOR_V
27f0: 45 52 53 49 4f 4e 20 3e 3d 20 34 20 26 26 20 5c  ERSION >= 4 && \
2800: 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f 5f 4d  .    defined(__M
2810: 53 56 43 52 54 5f 5f 29 0a 23 20 64 65 66 69 6e  SVCRT__).# defin
2820: 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d  e _USE_32BIT_TIM
2830: 45 5f 54 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 54  E_T.#endif../* T
2840: 68 65 20 70 75 62 6c 69 63 20 53 51 4c 69 74 65  he public SQLite
2850: 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
2860: 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49   _FILE_OFFSET_BI
2870: 54 53 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70  TS macro must ap
2880: 70 65 61 72 0a 2a 2a 20 66 69 72 73 74 20 69 6e  pear.** first in
2890: 20 51 4e 58 2e 20 20 41 6c 73 6f 2c 20 74 68 65   QNX.  Also, the
28a0: 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45   _USE_32BIT_TIME
28b0: 5f 54 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70  _T macro must ap
28c0: 70 65 61 72 20 66 69 72 73 74 20 66 6f 72 0a 2a  pear first for.*
28d0: 2a 20 4d 69 6e 47 57 2e 0a 2a 2f 0a 2f 2a 2a 2a  * MinGW..*/./***
28e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c  *********** Incl
28f0: 75 64 65 20 73 71 6c 69 74 65 33 2e 68 20 69 6e  ude sqlite3.h in
2900: 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73   the middle of s
2910: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a  qliteInt.h *****
2920: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a  **********/./***
2930: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69  *********** Begi
2940: 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 33 2e 68  n file sqlite3.h
2950: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
2960: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2970: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a  **********/./*.*
2980: 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72  * 2001 September
2990: 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75   15.**.** The au
29a0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
29b0: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
29c0: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
29d0: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
29e0: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
29f0: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
2a00: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
2a10: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
2a20: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
2a30: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
2a40: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
2a50: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
2a60: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
2a70: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
2a80: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
2a90: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
2aa0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
2ab0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2ac0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2ad0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2ae0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2af0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 65 61 64 65  **.** This heade
2b00: 72 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20 74  r file defines t
2b10: 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  he interface tha
2b20: 74 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  t the SQLite lib
2b30: 72 61 72 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73  rary.** presents
2b40: 20 74 6f 20 63 6c 69 65 6e 74 20 70 72 6f 67 72   to client progr
2b50: 61 6d 73 2e 20 20 49 66 20 61 20 43 2d 66 75 6e  ams.  If a C-fun
2b60: 63 74 69 6f 6e 2c 20 73 74 72 75 63 74 75 72 65  ction, structure
2b70: 2c 20 64 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f  , datatype,.** o
2b80: 72 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  r constant defin
2b90: 69 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61  ition does not a
2ba0: 70 70 65 61 72 20 69 6e 20 74 68 69 73 20 66 69  ppear in this fi
2bb0: 6c 65 2c 20 74 68 65 6e 20 69 74 20 69 73 0a 2a  le, then it is.*
2bc0: 2a 20 6e 6f 74 20 61 20 70 75 62 6c 69 73 68 65  * not a publishe
2bd0: 64 20 41 50 49 20 6f 66 20 53 51 4c 69 74 65 2c  d API of SQLite,
2be0: 20 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63   is subject to c
2bf0: 68 61 6e 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a  hange without.**
2c00: 20 6e 6f 74 69 63 65 2c 20 61 6e 64 20 73 68 6f   notice, and sho
2c10: 75 6c 64 20 6e 6f 74 20 62 65 20 72 65 66 65 72  uld not be refer
2c20: 65 6e 63 65 64 20 62 79 20 70 72 6f 67 72 61 6d  enced by program
2c30: 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74  s that use SQLit
2c40: 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66  e..**.** Some of
2c50: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 73   the definitions
2c60: 20 74 68 61 74 20 61 72 65 20 69 6e 20 74 68 69   that are in thi
2c70: 73 20 66 69 6c 65 20 61 72 65 20 6d 61 72 6b 65  s file are marke
2c80: 64 20 61 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d  d as.** "experim
2c90: 65 6e 74 61 6c 22 2e 20 20 45 78 70 65 72 69 6d  ental".  Experim
2ca0: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
2cb0: 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65   are normally ne
2cc0: 77 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 72 65  w.** features re
2cd0: 63 65 6e 74 6c 79 20 61 64 64 65 64 20 74 6f 20  cently added to 
2ce0: 53 51 4c 69 74 65 2e 20 20 57 65 20 64 6f 20 6e  SQLite.  We do n
2cf0: 6f 74 20 61 6e 74 69 63 69 70 61 74 65 20 63 68  ot anticipate ch
2d00: 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65  anges.** to expe
2d10: 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61  rimental interfa
2d20: 63 65 73 20 62 75 74 20 72 65 73 65 72 76 65 20  ces but reserve 
2d30: 74 68 65 20 72 69 67 68 74 20 74 6f 20 6d 61 6b  the right to mak
2d40: 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a  e minor changes.
2d50: 2a 2a 20 69 66 20 65 78 70 65 72 69 65 6e 63 65  ** if experience
2d60: 20 66 72 6f 6d 20 75 73 65 20 22 69 6e 20 74 68   from use "in th
2d70: 65 20 77 69 6c 64 22 20 73 75 67 67 65 73 74 20  e wild" suggest 
2d80: 73 75 63 68 20 63 68 61 6e 67 65 73 20 61 72 65  such changes are
2d90: 20 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20   prudent..**.** 
2da0: 54 68 65 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c  The official C-l
2db0: 61 6e 67 75 61 67 65 20 41 50 49 20 64 6f 63 75  anguage API docu
2dc0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 53 51  mentation for SQ
2dd0: 4c 69 74 65 20 69 73 20 64 65 72 69 76 65 64 0a  Lite is derived.
2de0: 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73  ** from comments
2df0: 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2e 20 20   in this file.  
2e00: 54 68 69 73 20 66 69 6c 65 20 69 73 20 74 68 65  This file is the
2e10: 20 61 75 74 68 6f 72 69 74 61 74 69 76 65 20 73   authoritative s
2e20: 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20  ource.** on how 
2e30: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
2e40: 73 20 61 72 65 20 73 75 70 70 6f 73 65 64 20 74  s are supposed t
2e50: 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a  o operate..**.**
2e60: 20 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 69   The name of thi
2e70: 73 20 66 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e  s file under con
2e80: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
2e90: 65 6d 65 6e 74 20 69 73 20 22 73 71 6c 69 74 65  ement is "sqlite
2ea0: 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d  .h.in"..** The m
2eb0: 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f  akefile makes so
2ec0: 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73  me minor changes
2ed0: 20 74 6f 20 74 68 69 73 20 66 69 6c 65 20 28 73   to this file (s
2ee0: 75 63 68 20 61 73 20 69 6e 73 65 72 74 69 6e 67  uch as inserting
2ef0: 0a 2a 2a 20 74 68 65 20 76 65 72 73 69 6f 6e 20  .** the version 
2f00: 6e 75 6d 62 65 72 29 20 61 6e 64 20 63 68 61 6e  number) and chan
2f10: 67 65 73 20 69 74 73 20 6e 61 6d 65 20 74 6f 20  ges its name to 
2f20: 22 73 71 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a  "sqlite3.h" as.*
2f30: 2a 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 75  * part of the bu
2f40: 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a  ild process..*/.
2f50: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 33 5f  #ifndef SQLITE3_
2f60: 48 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  H.#define SQLITE
2f70: 33 5f 48 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74  3_H.#include <st
2f80: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e  darg.h>     /* N
2f90: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65  eeded for the de
2fa0: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c  finition of va_l
2fb0: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61  ist */../*.** Ma
2fc0: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63  ke sure we can c
2fd0: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66  all this stuff f
2fe0: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20  rom C++..*/.#if 
2ff0: 30 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23  0.extern "C" {.#
3000: 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50 72  endif.../*.** Pr
3010: 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69 74  ovide the abilit
3020: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c 69  y to override li
3030: 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20 6f  nkage features o
3040: 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 2e  f the interface.
3050: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
3060: 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69  TE_EXTERN.# defi
3070: 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  ne SQLITE_EXTERN
3080: 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 23   extern.#endif.#
3090: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50  ifndef SQLITE_AP
30a0: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
30b0: 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69 66  E_API.#endif.#if
30c0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45 43  ndef SQLITE_CDEC
30d0: 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  L.# define SQLIT
30e0: 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a 23  E_CDECL.#endif.#
30f0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50  ifndef SQLITE_AP
3100: 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53  ICALL.# define S
3110: 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65  QLITE_APICALL.#e
3120: 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c  ndif.#ifndef SQL
3130: 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65  ITE_STDCALL.# de
3140: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43  fine SQLITE_STDC
3150: 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43 41  ALL SQLITE_APICA
3160: 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65  LL.#endif.#ifnde
3170: 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43  f SQLITE_CALLBAC
3180: 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  K.# define SQLIT
3190: 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64 69  E_CALLBACK.#endi
31a0: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
31b0: 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e 65  _SYSAPI.# define
31c0: 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a 23   SQLITE_SYSAPI.#
31d0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  endif../*.** The
31e0: 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20  se no-op macros 
31f0: 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e  are used in fron
3200: 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20  t of interfaces 
3210: 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a  to mark those.**
3220: 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65   interfaces as e
3230: 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64  ither deprecated
3240: 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   or experimental
3250: 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69  .  New applicati
3260: 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f  ons.** should no
3270: 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64  t use deprecated
3280: 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68   interfaces - th
3290: 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  ey are supported
32a0: 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a   for backwards.*
32b0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32c0: 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69  only.  Applicati
32d0: 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c  on writers shoul
32e0: 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a  d be aware that.
32f0: 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ** experimental 
3300: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73  interfaces are s
3310: 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
3320: 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73   in point releas
3330: 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es..**.** These 
3340: 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72  macros used to r
3350: 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75  esolve to variou
3360: 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69  s kinds of compi
3370: 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a  ler magic that.*
3380: 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65  * would generate
3390: 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65   warning message
33a0: 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65  s when they were
33b0: 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74   used.  But that
33c0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67  .** compiler mag
33d0: 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65  ic ended up gene
33e0: 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c  rating such a fl
33f0: 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f  urry of bug repo
3400: 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68  rts.** that we h
3410: 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c  ave taken it all
3420: 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61   out and gone ba
3430: 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70  ck to using simp
3440: 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f  le.** noop macro
3450: 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s..*/.#define SQ
3460: 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a  LITE_DEPRECATED.
3470: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
3480: 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a  XPERIMENTAL../*.
3490: 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20  ** Ensure these 
34a0: 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74  symbols were not
34b0: 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65   defined by some
34c0: 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72   previous header
34d0: 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66   file..*/.#ifdef
34e0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
34f0: 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56  # undef SQLITE_V
3500: 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69  ERSION.#endif.#i
3510: 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  fdef SQLITE_VERS
3520: 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64  ION_NUMBER.# und
3530: 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ef SQLITE_VERSIO
3540: 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a  N_NUMBER.#endif.
3550: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
3560: 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69   Compile-Time Li
3570: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
3580: 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  mbers.**.** ^(Th
3590: 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  e [SQLITE_VERSIO
35a0: 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  N] C preprocesso
35b0: 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73  r macro in the s
35c0: 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a  qlite3.h header.
35d0: 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20  ** evaluates to 
35e0: 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
35f0: 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c   that is the SQL
3600: 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74  ite version in t
3610: 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e  he.** format "X.
3620: 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20  Y.Z" where X is 
3630: 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f  the major versio
3640: 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73  n number (always
3650: 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65   3 for.** SQLite
3660: 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20  3) and Y is the 
3670: 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75  minor version nu
3680: 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68  mber and Z is th
3690: 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72  e release number
36a0: 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51  .)^.** ^(The [SQ
36b0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
36c0: 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73  BER] C preproces
36d0: 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76  sor macro resolv
36e0: 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  es to an integer
36f0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c  .** with the val
3700: 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20  ue (X*1000000 + 
3710: 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72  Y*1000 + Z) wher
3720: 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72  e X, Y, and Z ar
3730: 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75  e the same.** nu
3740: 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53  mbers used in [S
3750: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29  QLITE_VERSION].)
3760: 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ^.** The SQLITE_
3770: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66  VERSION_NUMBER f
3780: 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c  or any given rel
3790: 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77  ease of SQLite w
37a0: 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c  ill also.** be l
37b0: 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72  arger than the r
37c0: 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63  elease from whic
37d0: 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e  h it is derived.
37e0: 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a    Either Y will.
37f0: 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74  ** be held const
3800: 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62  ant and Z will b
3810: 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72  e incremented or
3820: 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20   else Y will be 
3830: 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61  incremented.** a
3840: 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73  nd Z will be res
3850: 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  et to zero..**.*
3860: 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f 6e  * Since [version
3870: 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65 6f   3.6.18] ([dateo
3880: 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a 20  f:3.6.18]), .** 
3890: 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f  SQLite source co
38a0: 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72  de has been stor
38b0: 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20  ed in the.** <a 
38c0: 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77  href="http://www
38d0: 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f  .fossil-scm.org/
38e0: 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75  ">Fossil configu
38f0: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e  ration managemen
3900: 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e  t.** system</a>.
3910: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
3920: 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76  URCE_ID macro ev
3930: 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20  aluates to.** a 
3940: 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64 65  string which ide
3950: 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69 63  ntifies a partic
3960: 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66  ular check-in of
3970: 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69   SQLite.** withi
3980: 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74  n its configurat
3990: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73  ion management s
39a0: 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c  ystem.  ^The SQL
39b0: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a  ITE_SOURCE_ID.**
39c0: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73   string contains
39d0: 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74 69   the date and ti
39e0: 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d  me of the check-
39f0: 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20  in (UTC) and an 
3a00: 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20  SHA1.** hash of 
3a10: 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63  the entire sourc
3a20: 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  e tree..**.** Se
3a30: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
3a40: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a  _libversion()],.
3a50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  ** [sqlite3_libv
3a60: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d  ersion_number()]
3a70: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  , [sqlite3_sourc
3a80: 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  eid()],.** [sqli
3a90: 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  te_version()] an
3aa0: 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65  d [sqlite_source
3ab0: 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  _id()]..*/.#defi
3ac0: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
3ad0: 4e 20 20 20 20 20 20 20 20 22 33 2e 31 37 2e 30  N        "3.17.0
3ae0: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ".#define SQLITE
3af0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
3b00: 33 30 31 37 30 30 30 0a 23 64 65 66 69 6e 65 20  3017000.#define 
3b10: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
3b20: 20 20 20 20 20 20 22 32 30 31 37 2d 30 32 2d 31        "2017-02-1
3b30: 33 20 31 36 3a 30 32 3a 34 30 20 61 64 61 30 35  3 16:02:40 ada05
3b40: 63 66 61 38 36 61 64 37 66 35 36 34 35 34 35 30  cfa86ad7f5645450
3b50: 61 63 37 61 32 61 32 31 63 39 61 61 36 65 35 37  ac7a2a21c9aa6e57
3b60: 64 32 63 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d2c"../*.** CAPI
3b70: 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
3b80: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
3b90: 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52  umbers.** KEYWOR
3ba0: 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73  DS: sqlite3_vers
3bb0: 69 6f 6e 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  ion sqlite3_sour
3bc0: 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ceid.**.** These
3bd0: 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76   interfaces prov
3be0: 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66  ide the same inf
3bf0: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20  ormation as the 
3c00: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
3c10: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  ,.** [SQLITE_VER
3c20: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e  SION_NUMBER], an
3c30: 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  d [SQLITE_SOURCE
3c40: 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73  _ID] C preproces
3c50: 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75  sor macros.** bu
3c60: 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64  t are associated
3c70: 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72   with the librar
3c80: 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  y instead of the
3c90: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e   header file.  ^
3ca0: 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f  (Cautious.** pro
3cb0: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69  grammers might i
3cc0: 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20  nclude assert() 
3cd0: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
3ce0: 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  eir application 
3cf0: 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61  to.** verify tha
3d00: 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  t values returne
3d10: 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72  d by these inter
3d20: 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20  faces match the 
3d30: 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65  macros in.** the
3d40: 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75   header, and thu
3d50: 73 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  s ensure that th
3d60: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
3d70: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
3d80: 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61  h matching libra
3d90: 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69  ry and header fi
3da0: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  les..**.** <bloc
3db0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
3dc0: 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f  assert( sqlite3_
3dd0: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
3de0: 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53  r()==SQLITE_VERS
3df0: 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a  ION_NUMBER );.**
3e00: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
3e10: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
3e20: 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  (),SQLITE_SOURCE
3e30: 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73  _ID)==0 );.** as
3e40: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
3e50: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
3e60: 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ),SQLITE_VERSION
3e70: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65  )==0 );.** </pre
3e80: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
3e90: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
3ea0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
3eb0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f  ring constant co
3ec0: 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20  ntains the text 
3ed0: 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  of [SQLITE_VERSI
3ee0: 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e  ON].** macro.  ^
3ef0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
3f00: 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f  ersion() functio
3f10: 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  n returns a poin
3f20: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f  ter to the.** to
3f30: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72   the sqlite3_ver
3f40: 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f  sion[] string co
3f50: 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c  nstant.  The sql
3f60: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
3f70: 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ).** function is
3f80: 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73   provided for us
3f90: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20  e in DLLs since 
3fa0: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c  DLL users usuall
3fb0: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a  y do not have.**
3fc0: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74   direct access t
3fd0: 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  o string constan
3fe0: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c  ts within the DL
3ff0: 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  L.  ^The.** sqli
4000: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
4010: 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e  umber() function
4020: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
4030: 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20  ger equal to.** 
4040: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
4050: 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73  NUMBER].  ^The s
4060: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
4070: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
4080: 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ns .** a pointer
4090: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   to a string con
40a0: 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75  stant whose valu
40b0: 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  e is the same as
40c0: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
40d0: 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72  _SOURCE_ID] C pr
40e0: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
40f0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
4100: 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  : [sqlite_versio
4110: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
4120: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
4130: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
4140: 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f  st char sqlite3_
4150: 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49  version[] = SQLI
4160: 54 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49  TE_VERSION;.SQLI
4170: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
4180: 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  r *sqlite3_libve
4190: 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c  rsion(void);.SQL
41a0: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
41b0: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
41c0: 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49  ceid(void);.SQLI
41d0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
41e0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
41f0: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  mber(void);../*.
4200: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
4210: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f  -Time Library Co
4220: 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  mpilation Option
4230: 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a  s Diagnostics.**
4240: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
4250: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
4260: 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  sed() function r
4270: 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a  eturns 0 or 1 .*
4280: 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65  * indicating whe
4290: 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69  ther the specifi
42a0: 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65  ed option was de
42b0: 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d  fined at .** com
42c0: 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65  pile time.  ^The
42d0: 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20   SQLITE_ prefix 
42e0: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66  may be omitted f
42f0: 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69  rom the .** opti
4300: 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74  on name passed t
4310: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  o sqlite3_compil
4320: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20  eoption_used(). 
4330: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
4340: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
4350: 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f  on_get() functio
4360: 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69  n allows iterati
4370: 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c  ng.** over the l
4380: 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74  ist of options t
4390: 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64  hat were defined
43a0: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
43b0: 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67   by.** returning
43c0: 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c   the N-th compil
43d0: 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74  e time option st
43e0: 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20  ring.  ^If N is 
43f0: 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a  out of range,.**
4400: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
4410: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74  option_get() ret
4420: 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
4430: 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ter.  ^The SQLIT
4440: 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73  E_ .** prefix is
4450: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e   omitted from an
4460: 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  y strings return
4470: 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
4480: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
4490: 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75  get()..**.** ^Su
44a0: 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69  pport for the di
44b0: 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f  agnostic functio
44c0: 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ns sqlite3_compi
44d0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a  leoption_used().
44e0: 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
44f0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
4500: 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  () may be omitte
4510: 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20  d by specifying 
4520: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
4530: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
4540: 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e  ON_DIAGS] option
4550: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
4560: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
4570: 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  : SQL functions 
4580: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
4590: 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e  ption_used()] an
45a0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  d.** [sqlite_com
45b0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
45c0: 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69  ] and the [compi
45d0: 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d  le_options pragm
45e0: 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  a]..*/.#ifndef S
45f0: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49  QLITE_OMIT_COMPI
4600: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53  LEOPTION_DIAGS.S
4610: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
4620: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
4630: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63  ion_used(const c
4640: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a  har *zOptName);.
4650: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
4660: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
4670: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
4680: 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a  (int N);.#endif.
4690: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
46a0: 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20   Test To See If 
46b0: 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54  The Library Is T
46c0: 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20  hreadsafe.**.** 
46d0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72  ^The sqlite3_thr
46e0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
46f0: 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  on returns zero 
4700: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
4710: 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d  * SQLite was com
4720: 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78  piled with mutex
4730: 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64  ing code omitted
4740: 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b   due to the.** [
4750: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
4760: 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
4770: 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74  option being set
4780: 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   to 0..**.** SQL
4790: 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69  ite can be compi
47a0: 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68  led with or with
47b0: 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68  out mutexes.  Wh
47c0: 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  en.** the [SQLIT
47d0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20  E_THREADSAFE] C 
47e0: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
47f0: 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75  ro is 1 or 2, mu
4800: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
4810: 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20  bled and SQLite 
4820: 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  is threadsafe.  
4830: 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  When the.** [SQL
4840: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
4850: 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20  macro is 0, .** 
4860: 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20  the mutexes are 
4870: 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75  omitted.  Withou
4880: 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69  t the mutexes, i
4890: 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a  t is not safe.**
48a0: 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63   to use SQLite c
48b0: 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d  oncurrently from
48c0: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74   more than one t
48d0: 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61  hread..**.** Ena
48e0: 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e  bling mutexes in
48f0: 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c  curs a measurabl
4900: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65  e performance pe
4910: 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20  nalty..** So if 
4920: 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f  speed is of utmo
4930: 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69  st importance, i
4940: 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f  t makes sense to
4950: 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20   disable.** the 
4960: 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f  mutexes.  But fo
4970: 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79  r maximum safety
4980: 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64  , mutexes should
4990: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   be enabled..** 
49a0: 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68  ^The default beh
49b0: 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74  avior is for mut
49c0: 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c  exes to be enabl
49d0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ed..**.** This i
49e0: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
49f0: 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69  used by an appli
4a00: 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73  cation to make s
4a10: 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
4a20: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
4a30: 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e  e that it is lin
4a40: 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73  king against was
4a50: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
4a60: 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65  * the desired se
4a70: 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51  tting of the [SQ
4a80: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
4a90: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68   macro..**.** Th
4aa0: 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c  is interface onl
4ab0: 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65  y reports on the
4ac0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75   compile-time mu
4ad0: 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f  tex setting.** o
4ae0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
4af0: 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20  READSAFE] flag. 
4b00: 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
4b10: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53  mpiled with.** S
4b20: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
4b30: 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75  =1 or =2 then mu
4b40: 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65  texes are enable
4b50: 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74  d by default but
4b60: 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79  .** can be fully
4b70: 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69   or partially di
4b80: 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63  sabled using a c
4b90: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
4ba0: 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74  config()].** wit
4bb0: 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c  h the verbs [SQL
4bc0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
4bd0: 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54  ETHREAD], [SQLIT
4be0: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
4bf0: 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  READ],.** or [SQ
4c00: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
4c10: 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20  ALIZED].  ^(The 
4c20: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
4c30: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74  the.** sqlite3_t
4c40: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
4c50: 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20  tion shows only 
4c60: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
4c70: 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74   setting of.** t
4c80: 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f  hread safety, no
4c90: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
4ca0: 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73  hanges to that s
4cb0: 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a  etting made by.*
4cc0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  * sqlite3_config
4cd0: 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  (). In other wor
4ce0: 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ds, the return v
4cf0: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
4d00: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a  3_threadsafe().*
4d10: 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62  * is unchanged b
4d20: 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  y calls to sqlit
4d30: 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a  e3_config().)^.*
4d40: 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  *.** See the [th
4d50: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
4d60: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
4d70: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
4d80: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  mation..*/.SQLIT
4d90: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
4da0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
4db0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
4dc0: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
4dd0: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a  nnection Handle.
4de0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61  ** KEYWORDS: {da
4df0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4e00: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  n} {database con
4e10: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  nections}.**.** 
4e20: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65  Each open SQLite
4e30: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70   database is rep
4e40: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f  resented by a po
4e50: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
4e60: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  ance of.** the o
4e70: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
4e80: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e  named "sqlite3".
4e90: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74    It is useful t
4ea0: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71  o think of an sq
4eb0: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72  lite3.** pointer
4ec0: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20   as an object.  
4ed0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
4ee0: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
4ef0: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
4f00: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
4f10: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
4f20: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63  are its construc
4f30: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74  tors, and [sqlit
4f40: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61  e3_close()].** a
4f50: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
4f60: 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20  e_v2()] are its 
4f70: 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68  destructors.  Th
4f80: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
4f90: 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  er.** interfaces
4fa0: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71   (such as.** [sq
4fb0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
4fc0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
4fd0: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
4fe0: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
4ff0: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
5000: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68  ] to name but th
5010: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65  ree) that are me
5020: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73  thods on an.** s
5030: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a  qlite3 object..*
5040: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
5050: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
5060: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
5070: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
5080: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  r Types.** KEYWO
5090: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
50a0: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
50b0: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
50c0: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
50d0: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
50e0: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
50f0: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
5100: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
5110: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
5120: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
5130: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
5140: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
5150: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
5160: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
5170: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
5180: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ype definitions.
5190: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69  .** The sqlite_i
51a0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
51b0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65  uint64 types are
51c0: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
51d0: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
51e0: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a  atibility only..
51f0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
5200: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
5210: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20  ite_int64 types 
5220: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
5230: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  r values.** betw
5240: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38  een -92233720368
5250: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32  54775808 and +92
5260: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
5270: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54  7 inclusive.  ^T
5280: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69  he.** sqlite3_ui
5290: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
52a0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  uint64 types can
52b0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
52c0: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65  alues .** betwee
52d0: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34  n 0 and +1844674
52e0: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e  4073709551615 in
52f0: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64  clusive..*/.#ifd
5300: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
5310: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
5320: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
5330: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 23   sqlite_int64;.#
5340: 20 69 66 64 65 66 20 53 51 4c 49 54 45 5f 55 49   ifdef SQLITE_UI
5350: 4e 54 36 34 5f 54 59 50 45 0a 20 20 20 20 74 79  NT64_TYPE.    ty
5360: 70 65 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e  pedef SQLITE_UIN
5370: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
5380: 75 69 6e 74 36 34 3b 0a 23 20 65 6c 73 65 20 20  uint64;.# else  
5390: 0a 20 20 20 20 74 79 70 65 64 65 66 20 75 6e 73  .    typedef uns
53a0: 69 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54  igned SQLITE_INT
53b0: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
53c0: 69 6e 74 36 34 3b 0a 23 20 65 6e 64 69 66 0a 23  int64;.# endif.#
53d0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
53e0: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
53f0: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
5400: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
5410: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
5420: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
5430: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
5440: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
5450: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
5460: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
5470: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
5480: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
5490: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
54a0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
54b0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
54c0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
54d0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
54e0: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
54f0: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
5500: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
5510: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
5520: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
5530: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
5540: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
5550: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
5560: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
5570: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
5580: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
5590: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
55a0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
55b0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
55c0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
55d0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
55e0: 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20  .** DESTRUCTOR: 
55f0: 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
5600: 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  he sqlite3_close
5610: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
5620: 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e  lose_v2() routin
5630: 65 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f  es are destructo
5640: 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73  rs.** for the [s
5650: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
5660: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
5670: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
5680: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
5690: 32 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  2() return [SQLI
56a0: 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65  TE_OK] if.** the
56b0: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
56c0: 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c  t is successfull
56d0: 79 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20  y destroyed and 
56e0: 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  all associated.*
56f0: 2a 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20  * resources are 
5700: 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a  deallocated..**.
5710: 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
5720: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
5730: 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
5740: 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72  h unfinalized pr
5750: 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
5760: 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68  ents or unfinish
5770: 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  ed sqlite3_backu
5780: 70 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73  p objects then s
5790: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a  qlite3_close().*
57a0: 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65  * will leave the
57b0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
57c0: 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65  tion open and re
57d0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
57e0: 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  Y]..** ^If sqlit
57f0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
5800: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66   called with unf
5810: 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65  inalized prepare
5820: 64 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  d statements.** 
5830: 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65  and/or unfinishe
5840: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
5850: 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  s, then the data
5860: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
5870: 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e  becomes.** an un
5880: 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20  usable "zombie" 
5890: 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d  which will autom
58a0: 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c  atically be deal
58b0: 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65  located when the
58c0: 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65  .** last prepare
58d0: 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66  d statement is f
58e0: 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20  inalized or the 
58f0: 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63  last sqlite3_bac
5900: 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68  kup is.** finish
5910: 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ed.  The sqlite3
5920: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65  _close_v2() inte
5930: 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65  rface is intende
5940: 64 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a  d for use with.*
5950: 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73  * host languages
5960: 20 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67   that are garbag
5970: 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64  e collected, and
5980: 20 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72   where the order
5990: 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73   in which.** des
59a0: 74 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c  tructors are cal
59b0: 6c 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79  led is arbitrary
59c0: 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
59d0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c  ions should [sql
59e0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
59f0: 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70  finalize] all [p
5a00: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
5a10: 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ts],.** [sqlite3
5a20: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
5a30: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
5a40: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a  andles], and .**
5a50: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
5a60: 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68  _finish | finish
5a70: 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62  ] all [sqlite3_b
5a80: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61  ackup] objects a
5a90: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
5aa0: 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  h the [sqlite3] 
5ab0: 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20  object prior to 
5ac0: 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c  attempting to cl
5ad0: 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20  ose the object. 
5ae0: 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   ^If.** sqlite3_
5af0: 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61  close_v2() is ca
5b00: 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62  lled on a [datab
5b10: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
5b20: 74 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a  that still has.*
5b30: 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70  * outstanding [p
5b40: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
5b50: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
5b60: 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b  es], and/or.** [
5b70: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
5b80: 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20  objects then it 
5b90: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
5ba0: 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c  OK] and the deal
5bb0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72  location.** of r
5bc0: 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65  esources is defe
5bd0: 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b  rred until all [
5be0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
5bf0: 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64  nts], [BLOB hand
5c00: 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71  les],.** and [sq
5c10: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
5c20: 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64  jects are also d
5c30: 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20  estroyed..**.** 
5c40: 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d  ^If an [sqlite3]
5c50: 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72   object is destr
5c60: 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61  oyed while a tra
5c70: 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nsaction is open
5c80: 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63  ,.** the transac
5c90: 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69  tion is automati
5ca0: 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
5cb0: 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70  k..**.** The C p
5cc0: 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
5cd0: 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61  ite3_close(C)] a
5ce0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
5cf0: 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74  e_v2(C)].** must
5d00: 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c   be either a NUL
5d10: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20  L.** pointer or 
5d20: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
5d30: 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61  ect pointer obta
5d40: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
5d50: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
5d60: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
5d70: 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
5d80: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
5d90: 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79  d not previously
5da0: 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c   closed..** ^Cal
5db0: 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f  ling sqlite3_clo
5dc0: 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  se() or sqlite3_
5dd0: 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20  close_v2() with 
5de0: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
5df0: 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  * argument is a 
5e00: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
5e10: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
5e20: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  t sqlite3_close(
5e30: 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
5e40: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
5e50: 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74  3_close_v2(sqlit
5e60: 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  e3*);../*.** The
5e70: 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c   type for a call
5e80: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  back function..*
5e90: 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79  * This is legacy
5ea0: 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e   and deprecated.
5eb0: 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64    It is included
5ec0: 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a   for historical.
5ed0: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
5ee0: 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75   and is not docu
5ef0: 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64  mented..*/.typed
5f00: 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33  ef int (*sqlite3
5f10: 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a  _callback)(void*
5f20: 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61  ,int,char**, cha
5f30: 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  r**);../*.** CAP
5f40: 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20  I3REF: One-Step 
5f50: 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20  Query Execution 
5f60: 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54  Interface.** MET
5f70: 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
5f80: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
5f90: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
5fa0: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  is a convenience
5fb0: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
5fc0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
5fd0: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
5fe0: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
5ff0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
6000: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61  ze()],.** that a
6010: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61  llows an applica
6020: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74  tion to run mult
6030: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20  iple statements 
6040: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75  of SQL.** withou
6050: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20  t having to use 
6060: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
6070: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
6080: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
6090: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20  rface runs zero 
60a0: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e  or more UTF-8 en
60b0: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f  coded,.** semico
60c0: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c  lon-separate SQL
60d0: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
60e0: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20  ed into its 2nd 
60f0: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20  argument,.** in 
6100: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
6110: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
6120: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20  nection] passed 
6130: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a  in as its 1st.**
6140: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
6150: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
6160: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64  ction of the 3rd
6170: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
6180: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
6190: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
61a0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66   it is invoked f
61b0: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72  or each result r
61c0: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74  ow.** coming out
61d0: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65   of the evaluate
61e0: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
61f0: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
6200: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
6210: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c  e3_exec() is rel
6220: 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ayed through to 
6230: 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74  the 1st argument
6240: 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c   of each.** call
6250: 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  back invocation.
6260: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
6270: 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  ck pointer to sq
6280: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
6290: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f  is NULL, then no
62a0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65   callback is eve
62b0: 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65  r invoked and re
62c0: 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a  sult rows are.**
62d0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
62e0: 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  ^If an error occ
62f0: 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61  urs while evalua
6300: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61  ting the SQL sta
6310: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
6320: 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  nto.** sqlite3_e
6330: 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63  xec(), then exec
6340: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
6350: 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73  rent statement s
6360: 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73  tops and.** subs
6370: 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74  equent statement
6380: 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20  s are skipped.  
6390: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
63a0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
63b0: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f  _exec().** is no
63c0: 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20  t NULL then any 
63d0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73  error message is
63e0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
63f0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  mory obtained.**
6400: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
6410: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73  alloc()] and pas
6420: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68  sed back through
6430: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
6440: 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  er..** To avoid 
6450: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68  memory leaks, th
6460: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
6470: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  ould invoke [sql
6480: 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
6490: 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  on error message
64a0: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
64b0: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  d through the 5t
64c0: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a  h parameter of.*
64d0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
64e0: 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72   after the error
64f0: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
6500: 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65  is no longer nee
6510: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ded..** ^If the 
6520: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
6530: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
6540: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
6550: 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63  no errors.** occ
6560: 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ur, then sqlite3
6570: 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65  _exec() sets the
6580: 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20   pointer in its 
6590: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
65a0: 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20  .** NULL before 
65b0: 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
65c0: 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f   ^If an sqlite3_
65d0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
65e0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
65f0: 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  , the sqlite3_ex
6600: 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  ec().** routine 
6610: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41  returns SQLITE_A
6620: 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76  BORT without inv
6630: 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61  oking the callba
6640: 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20  ck again and.** 
6650: 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20  without running 
6660: 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53  any subsequent S
6670: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
6680: 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72  *.** ^The 2nd ar
6690: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
66a0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
66b0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69  lback function i
66c0: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
66d0: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
66e0: 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20  e result.  ^The 
66f0: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  3rd argument to 
6700: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
6710: 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ().** callback i
6720: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
6730: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
6740: 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66  s obtained as if
6750: 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
6760: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
6770: 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63  , one for each c
6780: 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65  olumn.  ^If an e
6790: 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72  lement of a.** r
67a0: 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c  esult row is NUL
67b0: 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65  L then the corre
67c0: 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20  sponding string 
67d0: 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a  pointer for the.
67e0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
67f0: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  ) callback is a 
6800: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
6810: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
6820: 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   to the.** sqlit
6830: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
6840: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
6850: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
6860: 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68  rings where each
6870: 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73  .** entry repres
6880: 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ents the name of
6890: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72   corresponding r
68a0: 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20  esult column as 
68b0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
68c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
68d0: 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _name()]..**.** 
68e0: 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61  ^If the 2nd para
68f0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
6900: 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c  _exec() is a NUL
6910: 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69  L pointer, a poi
6920: 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d  nter.** to an em
6930: 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61  pty string, or a
6940: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f   pointer that co
6950: 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74  ntains only whit
6960: 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a  espace and/or .*
6970: 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20  * SQL comments, 
6980: 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74  then no SQL stat
6990: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
69a0: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74  ated and the dat
69b0: 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20  abase.** is not 
69c0: 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  changed..**.** R
69d0: 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a  estrictions:.**.
69e0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
69f0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
6a00: 6d 75 73 74 20 65 6e 73 75 72 65 20 74 68 61 74  must ensure that
6a10: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
6a20: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
6a30: 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20  ec().**      is 
6a40: 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e  a valid and open
6a50: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
6a60: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20  ction]..** <li> 
6a70: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
6a80: 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
6a90: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
6aa0: 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
6ab0: 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68  ed by.**      th
6ac0: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
6ad0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
6ae0: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
6af0: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
6b00: 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  g..** <li> The a
6b10: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
6b20: 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53  not modify the S
6b30: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
6b40: 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  t passed into.**
6b50: 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61        the 2nd pa
6b60: 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
6b70: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
6b80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
6b90: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f  s running..** </
6ba0: 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul>.*/.SQLITE_AP
6bb0: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  I int sqlite3_ex
6bc0: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
6bd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6be0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6bf0: 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
6c00: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
6c10: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  char *sql,      
6c20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6c30: 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
6c40: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
6c50: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
6c60: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
6c70: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
6c80: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
6c90: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  void *,   
6ca0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6cb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6cc0: 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
6cd0: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
6ce0: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
6cf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6d00: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
6d10: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
6d20: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
6d30: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
6d40: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
6d50: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
6d60: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
6d70: 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c  }.**.** Many SQL
6d80: 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ite functions re
6d90: 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20  turn an integer 
6da0: 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d  result code from
6db0: 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a   the set shown.*
6dc0: 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20  * here in order 
6dd0: 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63 63  to indicate succ
6de0: 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a  ess or failure..
6df0: 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20  **.** New error 
6e00: 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64  codes may be add
6e10: 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
6e20: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
6e30: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
6e40: 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
6e50: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
6e60: 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ns].*/.#define S
6e70: 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20  QLITE_OK        
6e80: 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73     0   /* Succes
6e90: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f  sful result */./
6ea0: 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65  * beginning-of-e
6eb0: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64  rror-codes */.#d
6ec0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
6ed0: 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a  OR        1   /*
6ee0: 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69   SQL error or mi
6ef0: 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a  ssing database *
6f00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6f10: 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20  _INTERNAL     2 
6f20: 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f    /* Internal lo
6f30: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c  gic error in SQL
6f40: 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ite */.#define S
6f50: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20  QLITE_PERM      
6f60: 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73     3   /* Access
6f70: 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69   permission deni
6f80: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
6f90: 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20  LITE_ABORT      
6fa0: 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63    4   /* Callbac
6fb0: 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73  k routine reques
6fc0: 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a  ted an abort */.
6fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
6fe0: 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20  USY         5   
6ff0: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
7000: 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  file is locked *
7010: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7020: 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20  _LOCKED       6 
7030: 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20    /* A table in 
7040: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
7050: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
7060: 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20  e SQLITE_NOMEM  
7070: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d        7   /* A m
7080: 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a  alloc() failed *
7090: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
70a0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20  _READONLY     8 
70b0: 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20    /* Attempt to 
70c0: 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79  write a readonly
70d0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
70e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
70f0: 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20  RRUPT    9   /* 
7100: 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e  Operation termin
7110: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
7120: 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64  interrupt()*/.#d
7130: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7140: 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a  RR       10   /*
7150: 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69   Some kind of di
7160: 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63  sk I/O error occ
7170: 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  urred */.#define
7180: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20   SQLITE_CORRUPT 
7190: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20      11   /* The 
71a0: 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d  database disk im
71b0: 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64  age is malformed
71c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
71d0: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31  TE_NOTFOUND    1
71e0: 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f  2   /* Unknown o
71f0: 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33  pcode in sqlite3
7200: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20  _file_control() 
7210: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7220: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
7230: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
7240: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
7250: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
7260: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7270: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
7280: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
7290: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
72a0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
72b0: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
72c0: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74  L    15   /* Dat
72d0: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
72e0: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
72f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
7300: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
7310: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
7320: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
7330: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
7340: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
7350: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
7360: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
7370: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
7380: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
7390: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
73a0: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
73b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
73c0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
73d0: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
73e0: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
73f0: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
7400: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
7410: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
7420: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
7430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
7440: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
7450: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
7460: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
7470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
7480: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
7490: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
74a0: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
74b0: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
74c0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
74d0: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
74e0: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
74f0: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
7500: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
7510: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
7520: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
7530: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
7540: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
7550: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
7560: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
7570: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
7580: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
7590: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
75a0: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
75b0: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
75c0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
75d0: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
75e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
75f0: 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e  E      27   /* N
7600: 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f  otifications fro
7610: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
7620: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7630: 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38  E_WARNING     28
7640: 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66     /* Warnings f
7650: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28  rom sqlite3_log(
7660: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
7670: 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20  ITE_ROW         
7680: 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  100  /* sqlite3_
7690: 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68  step() has anoth
76a0: 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a  er row ready */.
76b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
76c0: 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20  ONE        101  
76d0: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
76e0: 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  ) has finished e
76f0: 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65  xecuting */./* e
7700: 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65  nd-of-error-code
7710: 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  s */../*.** CAPI
7720: 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52  3REF: Extended R
7730: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
7740: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
7750: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64  ed result code d
7760: 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a  efinitions}.**.*
7770: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74  * In its default
7780: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
7790: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69  SQLite API routi
77a0: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  nes return one o
77b0: 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20  f 30 integer.** 
77c0: 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20  [result codes]. 
77d0: 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69   However, experi
77e0: 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74  ence has shown t
77f0: 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74  hat many of.** t
7800: 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65  hese result code
7810: 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65  s are too coarse
7820: 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20  -grained.  They 
7830: 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61  do not provide a
7840: 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d  s.** much inform
7850: 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62  ation about prob
7860: 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d  lems as programm
7870: 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20  ers might like. 
7880: 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f   In an effort to
7890: 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73  .** address this
78a0: 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  , newer versions
78b0: 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73   of SQLite (vers
78c0: 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61 74 65 6f  ion 3.3.8 [dateo
78d0: 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20  f:3.3.8].** and 
78e0: 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a  later) include.*
78f0: 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64  * support for ad
7900: 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20  ditional result 
7910: 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69  codes that provi
7920: 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64  de more detailed
7930: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
7940: 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68  about errors. Th
7950: 65 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65  ese [extended re
7960: 73 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20  sult codes] are 
7970: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
7980: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
7990: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
79a0: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
79b0: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
79c0: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
79d0: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f  codes()] API.  O
79e0: 72 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20  r, the extended 
79f0: 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  code for.** the 
7a00: 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f  most recent erro
7a10: 72 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65  r can be obtaine
7a20: 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
7a30: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
7a40: 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  code()]..*/.#def
7a50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7a60: 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20  _READ           
7a70: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7a80: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
7a90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
7aa0: 53 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20  SHORT_READ      
7ab0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
7ac0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
7ad0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57  e SQLITE_IOERR_W
7ae0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
7af0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7b00: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
7b10: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
7b20: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
7b30: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
7b40: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
7b50: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
7b60: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28  _FSYNC         (
7b70: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
7b80: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
7b90: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e  QLITE_IOERR_TRUN
7ba0: 43 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53  CATE          (S
7bb0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36  QLITE_IOERR | (6
7bc0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7bd0: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54  LITE_IOERR_FSTAT
7be0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7bf0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c  LITE_IOERR | (7<
7c00: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7c10: 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b  ITE_IOERR_UNLOCK
7c20: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
7c30: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c  ITE_IOERR | (8<<
7c40: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
7c50: 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20  TE_IOERR_RDLOCK 
7c60: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
7c70: 54 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38  TE_IOERR | (9<<8
7c80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7c90: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20  E_IOERR_DELETE  
7ca0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7cb0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38  E_IOERR | (10<<8
7cc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7cd0: 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20  E_IOERR_BLOCKED 
7ce0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7cf0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38  E_IOERR | (11<<8
7d00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7d10: 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20  E_IOERR_NOMEM   
7d20: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7d30: 45 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38  E_IOERR | (12<<8
7d40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7d50: 45 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20  E_IOERR_ACCESS  
7d60: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7d70: 45 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38  E_IOERR | (13<<8
7d80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7d90: 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53  E_IOERR_CHECKRES
7da0: 45 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54  ERVEDLOCK (SQLIT
7db0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38  E_IOERR | (14<<8
7dc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7dd0: 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20  E_IOERR_LOCK    
7de0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7df0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38  E_IOERR | (15<<8
7e00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7e10: 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20  E_IOERR_CLOSE   
7e20: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7e30: 45 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38  E_IOERR | (16<<8
7e40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7e50: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53  E_IOERR_DIR_CLOS
7e60: 45 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  E         (SQLIT
7e70: 45 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38  E_IOERR | (17<<8
7e80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7e90: 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20  E_IOERR_SHMOPEN 
7ea0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7eb0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38  E_IOERR | (18<<8
7ec0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7ed0: 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20  E_IOERR_SHMSIZE 
7ee0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7ef0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38  E_IOERR | (19<<8
7f00: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7f10: 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20  E_IOERR_SHMLOCK 
7f20: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7f30: 45 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38  E_IOERR | (20<<8
7f40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7f50: 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20  E_IOERR_SHMMAP  
7f60: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7f70: 45 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38  E_IOERR | (21<<8
7f80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7f90: 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20  E_IOERR_SEEK    
7fa0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7fb0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38  E_IOERR | (22<<8
7fc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7fd0: 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e  E_IOERR_DELETE_N
7fe0: 4f 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54  OENT      (SQLIT
7ff0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38  E_IOERR | (23<<8
8000: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
8010: 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20  E_IOERR_MMAP    
8020: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
8030: 45 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38  E_IOERR | (24<<8
8040: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
8050: 45 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50  E_IOERR_GETTEMPP
8060: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
8070: 45 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38  E_IOERR | (25<<8
8080: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
8090: 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48  E_IOERR_CONVPATH
80a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
80b0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38  E_IOERR | (26<<8
80c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
80d0: 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20  E_IOERR_VNODE   
80e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
80f0: 45 5f 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38  E_IOERR | (27<<8
8100: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
8110: 45 5f 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20  E_IOERR_AUTH    
8120: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
8130: 45 5f 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38  E_IOERR | (28<<8
8140: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
8150: 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43  E_LOCKED_SHAREDC
8160: 41 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54  ACHE      (SQLIT
8170: 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c  E_LOCKED |  (1<<
8180: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
8190: 54 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59  TE_BUSY_RECOVERY
81a0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
81b0: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c  TE_BUSY   |  (1<
81c0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
81d0: 49 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f  ITE_BUSY_SNAPSHO
81e0: 54 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  T           (SQL
81f0: 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32  ITE_BUSY   |  (2
8200: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
8210: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f  LITE_CANTOPEN_NO
8220: 54 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51  TEMPDIR      (SQ
8230: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
8240: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
8250: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
8260: 49 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28  ISDIR          (
8270: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
8280: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
8290: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
82a0: 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20  N_FULLPATH      
82b0: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
82c0: 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  N | (3<<8)).#def
82d0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
82e0: 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20  PEN_CONVPATH    
82f0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
8300: 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  PEN | (4<<8)).#d
8310: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
8320: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20  RUPT_VTAB       
8330: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52       (SQLITE_COR
8340: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  RUPT | (1<<8)).#
8350: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
8360: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20  ADONLY_RECOVERY 
8370: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
8380: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29  ADONLY | (1<<8))
8390: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
83a0: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43  READONLY_CANTLOC
83b0: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
83c0: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38  READONLY | (2<<8
83d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
83e0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42  E_READONLY_ROLLB
83f0: 41 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  ACK       (SQLIT
8400: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c  E_READONLY | (3<
8410: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
8420: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d  ITE_READONLY_DBM
8430: 4f 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c  OVED        (SQL
8440: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
8450: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
8460: 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c  QLITE_ABORT_ROLL
8470: 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53  BACK          (S
8480: 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32  QLITE_ABORT | (2
8490: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
84a0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
84b0: 43 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51  CHECK        (SQ
84c0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
84d0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
84e0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
84f0: 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20  INT_COMMITHOOK  
8500: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
8510: 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  INT | (2<<8)).#d
8520: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
8530: 53 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b  STRAINT_FOREIGNK
8540: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
8550: 53 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29  STRAINT | (3<<8)
8560: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
8570: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43  _CONSTRAINT_FUNC
8580: 54 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45  TION     (SQLITE
8590: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34  _CONSTRAINT | (4
85a0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
85b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
85c0: 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51  NOTNULL      (SQ
85d0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
85e0: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
85f0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
8600: 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20  INT_PRIMARYKEY  
8610: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
8620: 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  INT | (6<<8)).#d
8630: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
8640: 53 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20  STRAINT_TRIGGER 
8650: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
8660: 53 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29  STRAINT | (7<<8)
8670: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
8680: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51  _CONSTRAINT_UNIQ
8690: 55 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  UE       (SQLITE
86a0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38  _CONSTRAINT | (8
86b0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
86c0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
86d0: 56 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51  VTAB         (SQ
86e0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
86f0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
8700: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
8710: 49 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20  INT_ROWID       
8720: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
8730: 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64  INT |(10<<8)).#d
8740: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
8750: 49 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20  ICE_RECOVER_WAL 
8760: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54       (SQLITE_NOT
8770: 49 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ICE | (1<<8)).#d
8780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
8790: 49 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c  ICE_RECOVER_ROLL
87a0: 42 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54  BACK (SQLITE_NOT
87b0: 49 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ICE | (2<<8)).#d
87c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
87d0: 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20  NING_AUTOINDEX  
87e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52       (SQLITE_WAR
87f0: 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23  NING | (1<<8)).#
8800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
8810: 54 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20  TH_USER         
8820: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55        (SQLITE_AU
8830: 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  TH | (1<<8)).#de
8840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c  fine SQLITE_OK_L
8850: 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20  OAD_PERMANENTLY 
8860: 20 20 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c      (SQLITE_OK |
8870: 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20   (1<<8))../*.** 
8880: 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20  CAPI3REF: Flags 
8890: 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70  For File Open Op
88a0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  erations.**.** T
88b0: 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20  hese bit values 
88c0: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72  are intended for
88d0: 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33   use in the.** 3
88e0: 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
88f0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  the [sqlite3_ope
8900: 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63  n_v2()] interfac
8910: 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20  e and.** in the 
8920: 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
8930: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
8940: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e  s.xOpen] method.
8950: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
8960: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
8970: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8980: 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  001  /* Ok for s
8990: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
89a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
89b0: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
89c0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
89d0: 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  002  /* Ok for s
89e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
89f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8a00: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20  TE_OPEN_CREATE  
8a10: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8a20: 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  004  /* Ok for s
8a30: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
8a40: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8a50: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
8a60: 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30  CLOSE    0x00000
8a70: 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  008  /* VFS only
8a80: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8a90: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
8aa0: 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  E        0x00000
8ab0: 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  010  /* VFS only
8ac0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8ad0: 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58  TE_OPEN_AUTOPROX
8ae0: 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30  Y        0x00000
8af0: 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  020  /* VFS only
8b00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8b10: 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20  TE_OPEN_URI     
8b20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8b30: 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  040  /* Ok for s
8b40: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
8b50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8b60: 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20  TE_OPEN_MEMORY  
8b70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8b80: 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  080  /* Ok for s
8b90: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
8ba0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8bb0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20  TE_OPEN_MAIN_DB 
8bc0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8bd0: 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  100  /* VFS only
8be0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8bf0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20  TE_OPEN_TEMP_DB 
8c00: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8c10: 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  200  /* VFS only
8c20: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8c30: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
8c40: 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30  T_DB     0x00000
8c50: 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  400  /* VFS only
8c60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8c70: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55  TE_OPEN_MAIN_JOU
8c80: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30  RNAL     0x00000
8c90: 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  800  /* VFS only
8ca0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8cb0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
8cc0: 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31  RNAL     0x00001
8cd0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
8ce0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8cf0: 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e  TE_OPEN_SUBJOURN
8d00: 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32  AL       0x00002
8d10: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
8d20: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8d30: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
8d40: 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34  OURNAL   0x00004
8d50: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
8d60: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8d70: 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20  TE_OPEN_NOMUTEX 
8d80: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38           0x00008
8d90: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
8da0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
8db0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8dc0: 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
8dd0: 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30  X        0x00010
8de0: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
8df0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
8e00: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8e10: 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
8e20: 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30  CHE      0x00020
8e30: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
8e40: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
8e50: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8e60: 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
8e70: 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30  ACHE     0x00040
8e80: 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73  000  /* Ok for s
8e90: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
8ea0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8eb0: 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20  TE_OPEN_WAL     
8ec0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30           0x00080
8ed0: 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79  000  /* VFS only
8ee0: 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64   */../* Reserved
8ef0: 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  :               
8f00: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30            0x00F0
8f10: 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  0000 */../*.** C
8f20: 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20  API3REF: Device 
8f30: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a  Characteristics.
8f40: 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63  **.** The xDevic
8f50: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
8f60: 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b   method of the [
8f70: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8f80: 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ds].** object re
8f90: 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72  turns an integer
8fa0: 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74   which is a vect
8fb0: 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62  or of these.** b
8fc0: 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73  it values expres
8fd0: 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74  sing I/O charact
8fe0: 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20  eristics of the 
8ff0: 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20  mass storage.** 
9000: 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64  device that hold
9010: 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20  s the file that 
9020: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
9030: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65  methods].** refe
9040: 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs to..**.** The
9050: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
9060: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
9070: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
9080: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
9090: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
90a0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
90b0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
90c0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
90d0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
90e0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
90f0: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
9100: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
9110: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
9120: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
9130: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
9140: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
9150: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
9160: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
9170: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
9180: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
9190: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
91a0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
91b0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
91c0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
91d0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
91e0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
91f0: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
9200: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
9210: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
9220: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
9230: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
9240: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
9250: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
9260: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
9270: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
9280: 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ().  The SQLITE_
9290: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
92a0: 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72  OVERWRITE proper
92b0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a  ty means that.**
92c0: 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f   after reboot fo
92d0: 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20  llowing a crash 
92e0: 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74  or power loss, t
92f0: 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e  he only bytes in
9300: 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20   a.** file that 
9310: 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20  were written at 
9320: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
9330: 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65  level might have
9340: 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20   changed.** and 
9350: 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79  that adjacent by
9360: 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20  tes, even bytes 
9370: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
9380: 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75  sector are.** gu
9390: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75  aranteed to be u
93a0: 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53  nchanged.  The S
93b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
93c0: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
93d0: 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61  N.** flag indica
93e0: 74 65 73 20 74 68 61 74 20 61 20 66 69 6c 65 20  tes that a file 
93f0: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
9400: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
9410: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
9420: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
9430: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
9440: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
9450: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
9460: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
9470: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
9480: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
9490: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
94a0: 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  leges..*/.#defin
94b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
94c0: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
94d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
94e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
94f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
9500: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
9510: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
9520: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
9530: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20  MIC1K           
9540: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
9550: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9560: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
9570: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
9580: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
9590: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
95a0: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C4K             
95b0: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
95c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
95d0: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
95e0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
95f0: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
9600: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
9610: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  6K              
9620: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
9630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
9640: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
9650: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
9660: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
9670: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
9680: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
9690: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
96a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
96b0: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20  FE_APPEND       
96c0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
96d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
96e0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
96f0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
9700: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
9710: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
9720: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
9730: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64  N  0x00000800.#d
9740: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
9750: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
9760: 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30  RWRITE    0x0000
9770: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
9780: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
9790: 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  BLE             
97a0: 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a   0x00002000../*.
97b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
97c0: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
97d0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
97e0: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
97f0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
9800: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
9810: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
9820: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
9830: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
9840: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
9850: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
9860: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
9870: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
9880: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
9890: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
98a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
98b0: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
98c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
98d0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
98e0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
98f0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
9900: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
9910: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
9920: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
9930: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
9940: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
9950: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
9960: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
9970: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
9980: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
9990: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
99a0: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
99b0: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
99c0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
99d0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
99e0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
99f0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
9a00: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
9a10: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
9a20: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
9a30: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
9a40: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
9a50: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
9a60: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
9a70: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
9a80: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
9a90: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
9aa0: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
9ab0: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
9ac0: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
9ad0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
9ae0: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
9af0: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
9b00: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
9b10: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
9b20: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
9b30: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
9b40: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
9b50: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
9b60: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
9b70: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
9b80: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
9b90: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
9ba0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
9bb0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
9bc0: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
9bd0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
9be0: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
9bf0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
9c00: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
9c10: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
9c20: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
9c30: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
9c40: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
9c50: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
9c60: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
9c70: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
9c80: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
9c90: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
9ca0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
9cb0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
9cc0: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
9cd0: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
9ce0: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
9cf0: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
9d00: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
9d10: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
9d20: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
9d30: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
9d40: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
9d50: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
9d60: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
9d70: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
9d80: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
9d90: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
9da0: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
9db0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
9dc0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
9dd0: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
9de0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
9df0: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
9e00: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
9e10: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
9e20: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
9e30: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
9e40: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
9e50: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
9e60: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
9e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
9e80: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
9e90: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
9ea0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
9eb0: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
9ec0: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
9ed0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
9ee0: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
9ef0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
9f00: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
9f10: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
9f20: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
9f30: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
9f40: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
9f50: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
9f60: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
9f70: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
9f80: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
9f90: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
9fa0: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
9fb0: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
9fc0: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
9fd0: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
9fe0: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
9ff0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
a000: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
a010: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
a020: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
a030: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
a040: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
a050: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
a060: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
a070: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
a080: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
a090: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
a0a0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
a0b0: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
a0c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
a0d0: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
a0e0: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
a0f0: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
a100: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
a110: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
a120: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
a130: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
a140: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
a150: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
a160: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
a170: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
a180: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
a190: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
a1a0: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
a1b0: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
a1c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
a1d0: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
a1e0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
a1f0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
a200: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
a210: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
a220: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
a230: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
a240: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
a250: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
a260: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
a270: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
a280: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
a290: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
a2a0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
a2b0: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
a2c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
a2d0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
a2e0: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
a2f0: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
a300: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
a310: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
a320: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
a330: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
a340: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
a350: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
a360: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
a370: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
a380: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
a390: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
a3a0: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
a3b0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
a3c0: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
a3d0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
a3e0: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
a3f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
a400: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
a410: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
a420: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
a430: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
a440: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
a450: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
a460: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
a470: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
a480: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
a490: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
a4a0: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
a4b0: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
a4c0: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
a4d0: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
a4e0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
a4f0: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
a500: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
a510: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
a520: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
a530: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
a540: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
a550: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
a560: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
a570: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
a580: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
a590: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
a5a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
a5b0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
a5c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
a5d0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
a5e0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
a5f0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
a600: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
a610: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
a620: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
a630: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
a640: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
a650: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
a660: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
a670: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
a680: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
a690: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
a6a0: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
a6b0: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
a6c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
a6d0: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
a6e0: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
a6f0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
a700: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
a710: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
a720: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
a730: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
a740: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
a750: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
a760: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
a770: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
a780: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
a790: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
a7a0: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
a7b0: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
a7c0: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
a7d0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
a7e0: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
a7f0: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
a800: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
a810: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
a820: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
a830: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
a840: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
a850: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
a860: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
a870: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
a880: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
a890: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
a8a0: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
a8b0: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
a8c0: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
a8d0: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
a8e0: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
a8f0: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
a900: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
a910: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
a920: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
a930: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
a940: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
a950: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
a960: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
a970: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
a980: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
a990: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
a9a0: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
a9b0: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
a9c0: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
a9d0: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
a9e0: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
a9f0: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
aa00: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
aa10: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
aa20: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
aa30: 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74  .** A [file cont
aa40: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69  rol opcodes | li
aa50: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
aa60: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
aa70: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
aa80: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
aa90: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
aaa0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
aab0: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
aac0: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
aad0: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
aae0: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20  oid conflicts.  
aaf0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
ab00: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ons should.** re
ab10: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  turn [SQLITE_NOT
ab20: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20  FOUND] for file 
ab30: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
ab40: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
ab50: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a  .** recognize..*
ab60: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
ab70: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
ab80: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
ab90: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
aba0: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
abb0: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
abc0: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
abd0: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
abe0: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
abf0: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
ac00: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
ac10: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
ac20: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
ac30: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
ac40: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
ac50: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
ac60: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
ac70: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
ac80: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
ac90: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
aca0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
acb0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
acc0: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
acd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
ace0: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
acf0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
ad00: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
ad10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
ad20: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
ad30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
ad40: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
ad50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
ad60: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
ad70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
ad80: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
ad90: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
ada0: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
adb0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
adc0: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
add0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
ade0: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
adf0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
ae00: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
ae10: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
ae20: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
ae30: 5f 57 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c  _WHEN_OPEN].** <
ae40: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
ae50: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
ae60: 57 52 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  WRITE].** <li> [
ae70: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
ae80: 55 54 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  UTABLE].** </ul>
ae90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
aea0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
aeb0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
aec0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
aed0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
aee0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
aef0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
af00: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
af10: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
af20: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
af30: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
af40: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
af50: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
af60: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
af70: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
af80: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
af90: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
afa0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
afb0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
afc0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
afd0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
afe0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
aff0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
b000: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
b010: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
b020: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
b030: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
b040: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
b050: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
b060: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
b070: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
b080: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
b090: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
b0a0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
b0b0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
b0c0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
b0d0: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
b0e0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
b0f0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
b100: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
b110: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
b120: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
b130: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
b140: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
b150: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
b160: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
b170: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
b180: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
b190: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
b1a0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
b1b0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
b1c0: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
b1d0: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
b1e0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
b1f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
b200: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
b210: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
b220: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
b230: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
b240: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
b250: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
b260: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
b270: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
b280: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
b290: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
b2a0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
b2b0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
b2c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
b2d0: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
b2e0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
b2f0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
b300: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
b310: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
b320: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
b330: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
b340: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
b350: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
b360: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
b370: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
b380: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
b390: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
b3a0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
b3b0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
b3c0: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
b3d0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
b3e0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
b3f0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
b400: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
b410: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
b420: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
b430: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
b440: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
b450: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
b460: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
b470: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
b480: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
b490: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
b4a0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
b4b0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
b4c0: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
b4d0: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
b4e0: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
b4f0: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
b500: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
b510: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
b520: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
b530: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
b540: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
b550: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
b560: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
b570: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
b580: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
b590: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
b5a0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
b5b0: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
b5c0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
b5d0: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
b5e0: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
b5f0: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
b600: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
b610: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
b620: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
b630: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
b640: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
b650: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
b660: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
b670: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
b680: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
b690: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
b6a0: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
b6b0: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
b6c0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
b6d0: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
b6e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
b6f0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
b700: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b  rol Opcodes.** K
b710: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63  EYWORDS: {file c
b720: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20  ontrol opcodes} 
b730: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
b740: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  code}.**.** Thes
b750: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
b760: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
b770: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
b780: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
b790: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
b7a0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
b7b0: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
b7c0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
b7d0: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
b7e0: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ace..**.** <ul>.
b7f0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b800: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
b810: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b820: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
b830: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
b840: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
b850: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
b860: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
b870: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
b880: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
b890: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
b8a0: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
b8b0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
b8c0: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
b8d0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
b8e0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
b8f0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
b900: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
b910: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
b920: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
b930: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
b940: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
b950: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
b960: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
b970: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
b980: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f  testing and is o
b990: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68  nly available wh
b9a0: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  en the SQLITE_TE
b9b0: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  ST.** compile-ti
b9c0: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  me option is use
b9d0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
b9e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
b9f0: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
ba00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
ba10: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
ba20: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
ba30: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
ba40: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
ba50: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
ba60: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
ba70: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
ba80: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
ba90: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
baa0: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
bab0: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
bac0: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
bad0: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
bae0: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
baf0: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
bb00: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
bb10: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
bb20: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
bb30: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
bb40: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
bb50: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
bb60: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
bb70: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
bb80: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bb90: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
bba0: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
bbb0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
bbc0: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
bbd0: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
bbe0: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
bbf0: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
bc00: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
bc10: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
bc20: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
bc30: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
bc40: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
bc50: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
bc60: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
bc70: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
bc80: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
bc90: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
bca0: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
bcb0: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
bcc0: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
bcd0: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
bce0: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
bcf0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
bd00: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
bd10: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
bd20: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
bd30: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
bd40: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
bd50: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
bd60: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
bd70: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
bd80: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
bd90: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
bda0: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
bdb0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
bdc0: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
bdd0: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
bde0: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
bdf0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
be00: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
be10: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74  ated with a part
be20: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
be30: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
be40: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
be50: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
be60: 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  OINTER]..**.** <
be70: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
be80: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
be90: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
bea0: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
beb0: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
bec0: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
bed0: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
bee0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
bef0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
bf00: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
bf10: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65   journal file (e
bf20: 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f  ither.** the [ro
bf30: 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20  llback journal] 
bf40: 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68  or the [write-ah
bf50: 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20  ead log]) for a 
bf60: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
bf70: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
bf80: 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51  n.  See also [SQ
bf90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
bfa0: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
bfb0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bfc0: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
bfd0: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69  ].** No longer i
bfe0: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  n use..**.** <li
bff0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c000: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SYNC]].** The [S
c010: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
c020: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
c030: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
c040: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a   by SQLite and.*
c050: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  * sent to the VF
c060: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65  S immediately be
c070: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d  fore the xSync m
c080: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
c090: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73   on a.** databas
c0a0: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
c0b0: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53  r. Or, if the xS
c0c0: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f  ync method is no
c0d0: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65  t invoked .** be
c0e0: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68  cause the user h
c0f0: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51  as configured SQ
c100: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50  Lite with .** [P
c110: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
c120: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
c130: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69  ronous=OFF] it i
c140: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61  s invoked in pla
c150: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53  ce .** of the xS
c160: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d  ync method. In m
c170: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70  ost cases, the p
c180: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20  ointer argument 
c190: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74  passed with.** t
c1a0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
c1b0: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65   is NULL. Howeve
c1c0: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61  r, if the databa
c1d0: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67  se file is being
c1e0: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61   synced.** as pa
c1f0: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61  rt of a multi-da
c200: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74  tabase commit, t
c210: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  he argument poin
c220: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d  ts to a nul-term
c230: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
c240: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
c250: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73  transactions mas
c260: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  ter-journal file
c270: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61   name. VFSes tha
c280: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65  t .** do not nee
c290: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68  d this signal sh
c2a0: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
c2b0: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
c2c0: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a  . Applications .
c2d0: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ** should not ca
c2e0: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
c2f0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
c300: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
c310: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a  doing so may .**
c320: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
c330: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
c340: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
c350: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
c360: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
c370: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
c380: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d  OMMIT_PHASETWO]]
c390: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c3a0: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
c3b0: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73  SETWO] opcode is
c3c0: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
c3d0: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a  nally by SQLite.
c3e0: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74  ** and sent to t
c3f0: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74  he VFS after a t
c400: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62  ransaction has b
c410: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d  een committed im
c420: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74  mediately.** but
c430: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61   before the data
c440: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64  base is unlocked
c450: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  . VFSes that do 
c460: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
c470: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73  gnal.** should s
c480: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
c490: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
c4a0: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
c4b0: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  not call.** [sql
c4c0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
c4d0: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
c4e0: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
c4f0: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
c500: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  e .** operation 
c510: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
c520: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
c530: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
c540: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c550: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
c560: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
c570: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
c580: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
c590: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
c5a0: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
c5b0: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
c5c0: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
c5d0: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
c5e0: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
c5f0: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
c600: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
c610: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
c620: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
c630: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
c640: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
c650: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
c660: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
c670: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
c680: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
c690: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
c6a0: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
c6b0: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
c6c0: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
c6d0: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
c6e0: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
c6f0: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
c700: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
c710: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
c720: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
c730: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
c740: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
c750: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
c760: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
c770: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
c780: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
c790: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
c7a0: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
c7b0: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
c7c0: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
c7d0: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
c7e0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c7f0: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
c800: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
c810: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
c820: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
c830: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
c840: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
c850: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
c860: 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74  er i the new ret
c870: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65  ry count and the
c880: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67   second.** integ
c890: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e  er is the delay.
c8a0: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65    If either inte
c8b0: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ger is negative,
c8c0: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e   then the settin
c8d0: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  g.** is not chan
c8e0: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20  ged but instead 
c8f0: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
c900: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20  of that setting 
c910: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e  is written.** in
c920: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74  to the array ent
c930: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65  ry, allowing the
c940: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73   current retry s
c950: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a  ettings to be.**
c960: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
c970: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61  The zDbName para
c980: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64  meter is ignored
c990: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c9a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
c9b0: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65  ST_WAL]].** ^The
c9c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
c9d0: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f  ERSIST_WAL] opco
c9e0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
c9f0: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
ca00: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41  * persistent [WA
ca10: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20  L | Write Ahead 
ca20: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42  Log] setting.  B
ca30: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61  y default, the a
ca40: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74  uxiliary.** writ
ca50: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20  e ahead log and 
ca60: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
ca70: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61  les used for tra
ca80: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
ca90: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69  .** are automati
caa0: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68  cally deleted wh
cab0: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f  en the latest co
cac0: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20  nnection to the 
cad0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73  database.** clos
cae0: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72  es.  Setting per
caf0: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
cb00: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69   causes those fi
cb10: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61  les to persist a
cb20: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20  fter.** close.  
cb30: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66  Persisting the f
cb40: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77  iles is useful w
cb50: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73  hen other proces
cb60: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a  ses that do not.
cb70: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65  ** have write pe
cb80: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20  rmission on the 
cb90: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69  directory contai
cba0: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
cbb0: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74  e file want.** t
cbc0: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62  o read the datab
cbd0: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65  ase file, as the
cbe0: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20   WAL and shared 
cbf0: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73  memory files mus
cc00: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72  t exist.** in or
cc10: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  der for the data
cc20: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61  base to be reada
cc30: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68  ble.  The fourth
cc40: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
cc50: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
cc60: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
cc70: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
cc80: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
cc90: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
cca0: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
ccb0: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72  0 to disable per
ccc0: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
ccd0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
cce0: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41  persistent.** WA
ccf0: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  L mode.  If the 
cd00: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
cd10: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
cd20: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
cd30: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65  urrent.** WAL pe
cd40: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e  rsistence settin
cd50: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
cd60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
cd70: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
cd80: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
cd90: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
cda0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  E_OVERWRITE] opc
cdb0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
cdc0: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
cdd0: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70  ** persistent "p
cde0: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69  owersafe-overwri
cdf0: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65  te" or "PSOW" se
ce00: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57  tting.  The PSOW
ce10: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65   setting.** dete
ce20: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49  rmines the [SQLI
ce30: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
ce40: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69  FE_OVERWRITE] bi
ce50: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76  t of the.** xDev
ce60: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
ce70: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20  cs methods. The 
ce80: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
ce90: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
cea0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
ceb0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
cec0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
ced0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
cee0: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
cef0: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
cf00: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  le zero-damage m
cf10: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
cf20: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a  le zero-damage.*
cf30: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  * mode.  If the 
cf40: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
cf50: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
cf60: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
cf70: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64  urrent.** zero-d
cf80: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69  amage mode setti
cf90: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
cfa0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
cfb0: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
cfc0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f   [SQLITE_FCNTL_O
cfd0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
cfe0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   is invoked by S
cff0: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e  QLite after open
d000: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74  ing.** a write t
d010: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e  ransaction to in
d020: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c  dicate that, unl
d030: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64  ess it is rolled
d040: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a   back for some.*
d050: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e  * reason, the en
d060: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69  tire database fi
d070: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77  le will be overw
d080: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75  ritten by the cu
d090: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61  rrent .** transa
d0a0: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75  ction. This is u
d0b0: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70  sed by VACUUM op
d0c0: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
d0d0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
d0e0: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20  TL_VFSNAME]].** 
d0f0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
d100: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f  TL_VFSNAME] opco
d110: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
d120: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d  o obtain the nam
d130: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46  es of.** all [VF
d140: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20  Ses] in the VFS 
d150: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65  stack.  The name
d160: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53  s are of all VFS
d170: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a   shims and the.*
d180: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c  * final bottom-l
d190: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69  evel VFS are wri
d1a0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
d1b0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
d1c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
d1d0: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  oc()] and the re
d1e0: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69  sult is stored i
d1f0: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  n the char* vari
d200: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65  able.** that the
d210: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
d220: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69  r of [sqlite3_fi
d230: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f  le_control()] po
d240: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20  ints to..** The 
d250: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e  caller is respon
d260: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
d270: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65  g the memory whe
d280: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68  n done.  As with
d290: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e  .** all file-con
d2a0: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68  trol actions, th
d2b0: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e  ere is no guaran
d2c0: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69  tee that this wi
d2d0: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64  ll actually.** d
d2e0: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c  o anything.  Cal
d2f0: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74  lers should init
d300: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a  ialize the char*
d310: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e   variable to a N
d320: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ULL.** pointer i
d330: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65  n case this file
d340: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20  -control is not 
d350: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68  implemented.  Th
d360: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  is file-control.
d370: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ** is intended f
d380: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73  or diagnostic us
d390: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  e only..**.** <l
d3a0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
d3b0: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a  _VFS_POINTER]].*
d3c0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
d3d0: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
d3e0: 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61  ] opcode finds a
d3f0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
d400: 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46  top-level.** [VF
d410: 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69  Ses] currently i
d420: 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72  n use.  ^(The ar
d430: 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73  gument X in.** s
d440: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
d450: 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43  rol(db,SQLITE_FC
d460: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c  NTL_VFS_POINTER,
d470: 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66  X) must be.** of
d480: 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f   type "[sqlite3_
d490: 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20  vfs] **".  This 
d4a0: 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74  opcodes will set
d4b0: 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e   *X.** to a poin
d4c0: 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c  ter to the top-l
d4d0: 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e  evel VFS.)^.** ^
d4e0: 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d  When there are m
d4f0: 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d  ultiple VFS shim
d500: 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20  s in the stack, 
d510: 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64  this opcode find
d520: 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d  s the.** upper-m
d530: 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a  ost shim only..*
d540: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
d550: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d  E_FCNTL_PRAGMA]]
d560: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20  .** ^Whenever a 
d570: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
d580: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e  nt is parsed, an
d590: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
d5a0: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20  RAGMA] .** file 
d5b0: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20  control is sent 
d5c0: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c  to the open [sql
d5d0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
d5e0: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  t corresponding.
d5f0: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ** to the databa
d600: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68  se file to which
d610: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74   the pragma stat
d620: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54  ement refers. ^T
d630: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
d640: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  o the [SQLITE_FC
d650: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
d660: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61   control is an a
d670: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74  rray of.** point
d680: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28  ers to strings (
d690: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68  char**) in which
d6a0: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d   the second elem
d6b0: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79  ent of the array
d6c0: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
d6d0: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e  of the pragma an
d6e0: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d  d the third elem
d6f0: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ent is the argum
d700: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72  ent to the.** pr
d710: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20  agma or NULL if 
d720: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e  the pragma has n
d730: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  o argument.  ^Th
d740: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e  e handler for an
d750: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
d760: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
d770: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f  ontrol can optio
d780: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66  nally make the f
d790: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  irst element.** 
d7a0: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72  of the char** ar
d7b0: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20  gument point to 
d7c0: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  a string obtaine
d7d0: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
d7e0: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72  mprintf()].** or
d7f0: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
d800: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20  and that string 
d810: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
d820: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72  result of the pr
d830: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65  agma or.** the e
d840: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20  rror message if 
d850: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73  the pragma fails
d860: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51  . ^If the.** [SQ
d870: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
d880: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
d890: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
d8a0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20  NOTFOUND], then 
d8b0: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47  normal .** [PRAG
d8c0: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63  MA] processing c
d8d0: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74  ontinues.  ^If t
d8e0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
d8f0: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
d900: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
d910: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
d920: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73  en the parser as
d930: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
d940: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65  * VFS has handle
d950: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73  d the PRAGMA its
d960: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73  elf and the pars
d970: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e  er generates a n
d980: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64  o-op.** prepared
d990: 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65   statement if re
d9a0: 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e  sult string is N
d9b0: 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74  ULL, or that ret
d9c0: 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  urns a copy.** o
d9d0: 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72  f the result str
d9e0: 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e  ing if the strin
d9f0: 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a  g is non-NULL..*
da00: 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
da10: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
da20: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
da30: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
da40: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
da50: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
da60: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
da70: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
da80: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
da90: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
daa0: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
dab0: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
dac0: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
dad0: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
dae0: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
daf0: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
db00: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
db10: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
db20: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
db30: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
db40: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
db50: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
db60: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
db70: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
db80: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
db90: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
dba0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
dbb0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
dbc0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
dbd0: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
dbe0: 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  LER].** file-con
dbf0: 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f  trol may be invo
dc00: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  ked by SQLite on
dc10: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
dc20: 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f  le handle.** sho
dc30: 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73  rtly after it is
dc40: 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72   opened in order
dc50: 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75   to provide a cu
dc60: 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63  stom VFS with ac
dc70: 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  cess.** to the c
dc80: 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d  onnections busy-
dc90: 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
dca0: 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  . The argument i
dcb0: 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20  s of type (void 
dcc0: 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61  **).** - an arra
dcd0: 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a  y of two (void *
dce0: 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69  ) values. The fi
dcf0: 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74  rst (void *) act
dd00: 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20  ually points.** 
dd10: 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
dd20: 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76   type (int (*)(v
dd30: 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65  oid *)). In orde
dd40: 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20  r to invoke the 
dd50: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62  connections.** b
dd60: 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69  usy-handler, thi
dd70: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  s function shoul
dd80: 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  d be invoked wit
dd90: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f  h the second (vo
dda0: 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20  id *) in.** the 
ddb0: 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c  array as the onl
ddc0: 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69  y argument. If i
ddd0: 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  t returns non-ze
dde0: 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65  ro, then the ope
ddf0: 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  ration.** should
de00: 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20   be retried. If 
de10: 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  it returns zero,
de20: 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20   the custom VFS 
de30: 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74  should abandon t
de40: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70  he.** current op
de50: 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  eration..**.** <
de60: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
de70: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d  L_TEMPFILENAME]]
de80: 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e  .** ^Application
de90: 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20   can invoke the 
dea0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
deb0: 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65  MPFILENAME] file
dec0: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68  -control.** to h
ded0: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72  ave SQLite gener
dee0: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61  ate a.** tempora
def0: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e  ry filename usin
df00: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
df10: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c  ithm that is fol
df20: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74  lowed to generat
df30: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
df40: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d  ilenames for TEM
df50: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68  P tables and oth
df60: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73  er internal uses
df70: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65  .  The.** argume
df80: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  nt should be a c
df90: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  har** which will
dfa0: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20   be filled with 
dfb0: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
dfc0: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
dfd0: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
dfe0: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
dff0: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65  c()].  The calle
e000: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f  r should.** invo
e010: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
e020: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c  ()] on the resul
e030: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d  t to avoid a mem
e040: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20  ory leak..**.** 
e050: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
e060: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  TL_MMAP_SIZE]].*
e070: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
e080: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
e090: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
e0a0: 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20  sed to query or 
e0b0: 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d  set the.** maxim
e0c0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
e0d0: 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  es that will be 
e0e0: 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d  used for memory-
e0f0: 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54  mapped I/O..** T
e100: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
e110: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
e120: 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69  lue of type sqli
e130: 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a  te3_int64 that.*
e140: 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79  * is an advisory
e150: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
e160: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
e170: 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d  file to memory m
e180: 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e  ap.  The.** poin
e190: 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74  ter is overwritt
e1a0: 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20  en with the old 
e1b0: 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69  value.  The limi
e1c0: 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  t is not changed
e1d0: 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65   if.** the value
e1e0: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e   originally poin
e1f0: 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69  ted to is negati
e200: 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63  ve, and so the c
e210: 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a  urrent limit .**
e220: 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20   can be queried 
e230: 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20  by passing in a 
e240: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67  pointer to a neg
e250: 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54  ative number.  T
e260: 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  his.** file-cont
e270: 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65  rol is used inte
e280: 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d  rnally to implem
e290: 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  ent [PRAGMA mmap
e2a0: 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  _size]..**.** <l
e2b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
e2c0: 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20  _TRACE]].** The 
e2d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
e2e0: 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ACE] file contro
e2f0: 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73  l provides advis
e300: 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ory information.
e310: 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62  ** to the VFS ab
e320: 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67  out what the hig
e330: 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68  her layers of th
e340: 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61  e SQLite stack a
e350: 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69  re doing..** Thi
e360: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
e370: 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56  s used by some V
e380: 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63  FS activity trac
e390: 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20  ing [shims]..** 
e3a0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
e3b0: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
e3c0: 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65  d string.  Highe
e3d0: 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a  r layers in the.
e3e0: 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  ** SQLite stack 
e3f0: 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73  may generate ins
e400: 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66  tances of this f
e410: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a  ile control if.*
e420: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  * the [SQLITE_US
e430: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63  E_FCNTL_TRACE] c
e440: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
e450: 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
e460: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
e470: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
e480: 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  D]].** The [SQLI
e490: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
e4a0: 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ED] file control
e4b0: 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20   interprets its 
e4c0: 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a  argument as a.**
e4d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
e4e0: 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72  nteger and it wr
e4f0: 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69  ites a boolean i
e500: 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
e510: 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e   depending.** on
e520: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
e530: 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65  the file has bee
e540: 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64  n renamed, moved
e550: 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e  , or deleted sin
e560: 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72  ce it.** was fir
e570: 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  st opened..**.**
e580: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
e590: 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41  NTL_WIN32_GET_HA
e5a0: 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NDLE]].** The [S
e5b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
e5c0: 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70  2_GET_HANDLE] op
e5d0: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
e5e0: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a   to obtain the.*
e5f0: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74  * underlying nat
e600: 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  ive file handle 
e610: 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
e620: 61 20 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20  a file handle.  
e630: 54 68 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e  This file.** con
e640: 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20  trol interprets 
e650: 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20  its argument as 
e660: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e  a pointer to a n
e670: 61 74 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c  ative file handl
e680: 65 20 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20  e and.** writes 
e690: 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61  the resulting va
e6a0: 6c 75 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  lue there..**.**
e6b0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
e6c0: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
e6d0: 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NDLE]].** The [S
e6e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
e6f0: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70  2_SET_HANDLE] op
e700: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
e710: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
e720: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
e730: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
e740: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77  rol method to sw
e750: 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64  ap the file hand
e760: 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a  le with the one.
e770: 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
e780: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
e790: 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69  nt.  This capabi
e7a0: 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72  lity is used dur
e7b0: 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61  ing testing.** a
e7c0: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
e7d0: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
e7e0: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69  en SQLITE_TEST i
e7f0: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  s defined..**.**
e800: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
e810: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a  NTL_WAL_BLOCK]].
e820: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
e830: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20  CNTL_WAL_BLOCK] 
e840: 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74  is a signal to t
e850: 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61  he VFS layer tha
e860: 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65  t it might.** be
e870: 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f   advantageous to
e880: 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65   block on the ne
e890: 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74  xt WAL lock if t
e8a0: 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69  he lock is not i
e8b0: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76  mmediately.** av
e8c0: 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41  ailable.  The WA
e8d0: 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75  L subsystem issu
e8e0: 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64  es this signal d
e8f0: 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69  uring rare.** ci
e900: 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f  rcumstances in o
e910: 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72  rder to fix a pr
e920: 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72  oblem with prior
e930: 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ity inversion..*
e940: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
e950: 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65  hould <em>not</e
e960: 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65  m> use this file
e970: 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  -control..**.** 
e980: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
e990: 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54  TL_ZIPVFS]].** T
e9a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
e9b0: 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20  _ZIPVFS] opcode 
e9c0: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
e9d0: 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41  y zipvfs only. A
e9e0: 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20  ll other.** VFS 
e9f0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
ea00: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
ea10: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a  r this opcode..*
ea20: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ea30: 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a  E_FCNTL_RBU]].**
ea40: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
ea50: 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69  TL_RBU] opcode i
ea60: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
ea70: 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
ea80: 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20   used by.** the 
ea90: 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e  RBU extension on
eaa0: 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56  ly.  All other V
eab0: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  FS should return
eac0: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
ead0: 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63   for.** this opc
eae0: 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ode.  .** </ul>.
eaf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
eb00: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
eb10: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
eb20: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
eb30: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
eb40: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32  ROXYFILE       2
eb50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
eb60: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
eb70: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a  OXYFILE       3.
eb80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
eb90: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  CNTL_LAST_ERRNO 
eba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
ebb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ebc0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
ebd0: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
ebe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ebf0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
ec00: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
ec10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ec20: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
ec30: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
ec40: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ec50: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
ec60: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
ec70: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ec80: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
ec90: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
eca0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
ecb0: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
ecc0: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
ecd0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
ece0: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
ecf0: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
ed00: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
ed10: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
ed20: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
ed30: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
ed40: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
ed50: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
ed60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ed70: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
ed80: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
ed90: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
eda0: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
edb0: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
edc0: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
edd0: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
ede0: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
edf0: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
ee00: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
ee10: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
ee20: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20  _FCNTL_TRACE    
ee30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
ee40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ee50: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20  FCNTL_HAS_MOVED 
ee60: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a               20.
ee70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ee80: 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20  CNTL_SYNC       
ee90: 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23              21.#
eea0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
eeb0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
eec0: 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64  TWO        22.#d
eed0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
eee0: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
eef0: 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65  DLE       23.#de
ef00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ef10: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20  L_WAL_BLOCK     
ef20: 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66           24.#def
ef30: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ef40: 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20  _ZIPVFS         
ef50: 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69          25.#defi
ef60: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ef70: 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20  RBU             
ef80: 20 20 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e         26.#defin
ef90: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
efa0: 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  FS_POINTER      
efb0: 20 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65        27.#define
efc0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f   SQLITE_FCNTL_JO
efd0: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20  URNAL_POINTER   
efe0: 20 20 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20       28.#define 
eff0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
f000: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 20  32_GET_HANDLE   
f010: 20 20 20 20 32 39 0a 23 64 65 66 69 6e 65 20 53      29.#define S
f020: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20  QLITE_FCNTL_PDB 
f030: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
f040: 20 20 20 33 30 0a 0a 2f 2a 20 64 65 70 72 65 63     30../* deprec
f050: 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64  ated names */.#d
f060: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54  efine SQLITE_GET
f070: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
f080: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
f090: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
f0a0: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
f0b0: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
f0c0: 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f  ILE      SQLITE_
f0d0: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
f0e0: 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20  OXYFILE.#define 
f0f0: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e  SQLITE_LAST_ERRN
f100: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 53 51  O             SQ
f110: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f  LITE_FCNTL_LAST_
f120: 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  ERRNO.../*.** CA
f130: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
f140: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
f150: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
f160: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
f170: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
f180: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
f190: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
f1a0: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
f1b0: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
f1c0: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
f1d0: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
f1e0: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
f1f0: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
f200: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
f210: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
f220: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
f230: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
f240: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
f250: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
f260: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
f270: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
f280: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
f290: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
f2a0: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
f2b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f  .** CAPI3REF: Lo
f2c0: 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e  adable Extension
f2d0: 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70   Thunk.**.** A p
f2e0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70  ointer to the op
f2f0: 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69  aque sqlite3_api
f300: 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74  _routines struct
f310: 75 72 65 20 69 73 20 70 61 73 73 65 64 20 61 73  ure is passed as
f320: 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20 70 61  .** the third pa
f330: 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79  rameter to entry
f340: 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64   points of [load
f350: 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d  able extensions]
f360: 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63  .  This.** struc
f370: 74 75 72 65 20 6d 75 73 74 20 62 65 20 74 79 70  ture must be typ
f380: 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20  edefed in order 
f390: 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63  to work around c
f3a0: 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73  ompiler warnings
f3b0: 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74  .** on some plat
f3c0: 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  forms..*/.typede
f3d0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
f3e0: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71  _api_routines sq
f3f0: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
f400: 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  es;../*.** CAPI3
f410: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
f420: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
f430: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
f440: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
f450: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
f460: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
f470: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
f480: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
f490: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
f4a0: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
f4b0: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
f4c0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
f4d0: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
f4e0: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
f4f0: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
f500: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
f510: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
f520: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
f530: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
f540: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
f550: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
f560: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
f570: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
f580: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
f590: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
f5a0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
f5b0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
f5c0: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
f5d0: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
f5e0: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
f5f0: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
f600: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
f610: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
f620: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
f630: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
f640: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
f650: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
f660: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
f670: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
f680: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
f690: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
f6a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
f6b0: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
f6c0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
f6d0: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
f6e0: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
f6f0: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
f700: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
f710: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
f720: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
f730: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
f740: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
f750: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
f760: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
f770: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
f780: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
f790: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
f7a0: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
f7b0: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
f7c0: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
f7d0: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
f7e0: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
f7f0: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
f800: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
f810: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
f820: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
f830: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
f840: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
f850: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
f860: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
f870: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
f880: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
f890: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
f8a0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
f8b0: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
f8c0: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
f8d0: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
f8e0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
f8f0: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
f900: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
f910: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
f920: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
f930: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
f940: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
f950: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
f960: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
f970: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
f980: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
f990: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
f9a0: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
f9b0: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
f9c0: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
f9d0: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
f9e0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
f9f0: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
fa00: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
fa10: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
fa20: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
fa30: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
fa40: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
fa50: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
fa60: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
fa70: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
fa80: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
fa90: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
faa0: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
fab0: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
fac0: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
fad0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
fae0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
faf0: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
fb00: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
fb10: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
fb20: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
fb30: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
fb40: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
fb50: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
fb60: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
fb70: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
fb80: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
fb90: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
fba0: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
fbb0: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
fbc0: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
fbd0: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
fbe0: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
fbf0: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
fc00: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
fc10: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
fc20: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
fc30: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
fc40: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
fc50: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
fc60: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
fc70: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
fc80: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
fc90: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
fca0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
fcb0: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
fcc0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
fcd0: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
fce0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
fcf0: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
fd00: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
fd10: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
fd20: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
fd30: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
fd40: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
fd50: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
fd60: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
fd70: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
fd80: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
fd90: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
fda0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
fdb0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
fdc0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
fdd0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
fde0: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
fdf0: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
fe00: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
fe10: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
fe20: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
fe30: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
fe40: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
fe50: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
fe60: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
fe70: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
fe80: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
fe90: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
fea0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
feb0: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
fec0: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
fed0: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
fee0: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
fef0: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
ff00: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
ff10: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
ff20: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
ff30: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
ff40: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
ff50: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
ff60: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
ff70: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
ff80: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
ff90: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
ffa0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
ffb0: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
ffc0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ffd0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
ffe0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
fff0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
10000 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
10010 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
10020 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
10030 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
10040 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
10050 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
10060 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
10070 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
10080 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
10090 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
100a0 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
100b0 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
100c0 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
100d0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
100e0 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
100f0 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
10100 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
10110 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
10120 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
10130 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
10140 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
10150 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
10160 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
10170 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
10180 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
10190 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
101a0 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
101b0 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
101c0 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
101d0 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
101e0 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
101f0 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
10200 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
10210 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
10220 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
10230 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
10240 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
10250 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
10260 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
10270 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
10280 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
10290 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
102a0 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
102b0 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
102c0 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
102d0 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
102e0 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
102f0 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
10300 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
10310 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
10320 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
10330 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
10340 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
10350 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
10360 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
10370 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
10380 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
10390 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
103a0 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
103b0 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
103c0 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
103d0 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
103e0 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
103f0 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
10400 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
10410 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
10420 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
10430 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
10440 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
10450 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
10460 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
10470 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
10480 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
10490 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
104a0 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
104b0 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
104c0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
104d0 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
104e0 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
104f0 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
10500 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
10510 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
10520 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
10530 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
10540 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
10550 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
10560 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
10570 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
10580 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
10590 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
105a0 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
105b0 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
105c0 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
105d0 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
105e0 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
105f0 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
10600 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
10610 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
10620 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
10630 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
10640 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
10650 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
10660 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
10670 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
10680 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
10690 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
106a0 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
106b0 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
106c0 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
106d0 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
106e0 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
106f0 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
10700 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
10710 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
10720 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
10730 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
10740 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
10750 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
10760 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
10770 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
10780 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
10790 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
107a0 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
107b0 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
107c0 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
107d0 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
107e0 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
107f0 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
10800 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
10810 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
10820 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
10830 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
10840 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
10850 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
10860 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
10870 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
10880 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
10890 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
108a0 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
108b0 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
108c0 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
108d0 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
108e0 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
108f0 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
10900 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
10910 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
10920 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
10930 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
10940 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
10950 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
10960 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
10970 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
10980 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
10990 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
109a0 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
109b0 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
109c0 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
109d0 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
109e0 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
109f0 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
10a00 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
10a10 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
10a20 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
10a30 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
10a40 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
10a50 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
10a60 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
10a70 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
10a80 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
10a90 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
10aa0 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
10ab0 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
10ac0 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
10ad0 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
10ae0 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
10af0 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
10b00 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
10b10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
10b20 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
10b30 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
10b40 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
10b50 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
10b60 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
10b70 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
10b80 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
10b90 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
10ba0 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
10bb0 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
10bc0 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
10bd0 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
10be0 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
10bf0 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
10c00 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
10c10 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
10c20 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
10c30 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
10c40 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
10c50 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
10c60 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
10c70 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
10c80 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
10c90 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
10ca0 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
10cb0 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
10cc0 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
10cd0 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
10ce0 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
10cf0 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
10d00 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
10d10 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
10d20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
10d30 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
10d40 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
10d50 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
10d60 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
10d70 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
10d80 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
10d90 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
10da0 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
10db0 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
10dc0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
10dd0 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
10de0 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
10df0 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
10e00 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
10e10 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
10e20 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
10e30 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
10e40 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
10e50 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
10e60 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
10e70 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
10e80 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
10e90 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
10ea0 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
10eb0 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
10ec0 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
10ed0 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
10ee0 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
10ef0 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
10f00 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
10f10 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
10f20 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
10f30 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
10f40 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
10f50 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
10f60 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
10f70 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
10f80 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
10f90 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
10fa0 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
10fb0 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
10fc0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
10fd0 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
10fe0 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
10ff0 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
11000 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
11010 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
11020 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
11030 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
11040 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
11050 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
11060 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
11070 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
11080 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
11090 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
110a0 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
110b0 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
110c0 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
110d0 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
110e0 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
110f0 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
11100 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
11110 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
11120 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
11130 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
11140 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
11150 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
11160 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
11170 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
11180 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
11190 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
111a0 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
111b0 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
111c0 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
111d0 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
111e0 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
111f0 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
11200 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
11210 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
11220 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
11230 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
11240 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
11250 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
11260 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
11270 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
11280 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
11290 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
112a0 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
112b0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
112c0 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
112d0 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
112e0 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
112f0 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
11300 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
11310 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
11320 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
11330 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
11340 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
11350 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
11360 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
11370 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
11380 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
11390 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
113a0 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
113b0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
113c0 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
113d0 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
113e0 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
113f0 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
11400 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
11410 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
11420 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
11430 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
11440 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
11450 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
11460 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
11470 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
11480 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
11490 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
114a0 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
114b0 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
114c0 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
114d0 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
114e0 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
114f0 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
11500 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
11510 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
11520 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
11530 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
11540 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
11550 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
11560 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
11570 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
11580 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
11590 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
115a0 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
115b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
115c0 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
115d0 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
115e0 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
115f0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
11600 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
11610 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
11620 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
11630 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
11640 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
11650 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
11660 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
11670 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
11680 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
11690 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
116a0 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
116b0 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
116c0 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
116d0 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
116e0 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
116f0 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
11700 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
11710 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
11720 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
11730 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
11740 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
11750 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
11760 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
11770 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
11780 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
11790 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
117a0 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
117b0 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
117c0 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
117d0 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
117e0 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
117f0 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
11800 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
11810 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
11820 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
11830 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
11840 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
11850 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
11860 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
11870 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
11880 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
11890 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
118a0 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
118b0 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
118c0 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
118d0 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
118e0 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
118f0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
11900 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
11910 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
11920 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
11930 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
11940 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
11950 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
11960 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
11970 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
11980 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
11990 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
119a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
119b0 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
119c0 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
119d0 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
119e0 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
119f0 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
11a00 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
11a10 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
11a20 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  nded in future v
11a30 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
11a40 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
11a50 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
11a60 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
11a70 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
11a80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11a90 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
11aa0 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
11ab0 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
11ac0 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
11ad0 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
11ae0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
11af0 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
11b00 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
11b10 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
11b20 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
11b30 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
11b40 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
11b50 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
11b60 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
11b70 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
11b80 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
11b90 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
11ba0 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
11bb0 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
11bc0 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
11bd0 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
11be0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
11bf0 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
11c00 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
11c10 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
11c20 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
11c30 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
11c40 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
11c50 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
11c60 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
11c70 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
11c80 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
11c90 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
11ca0 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
11cb0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
11cc0 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
11cd0 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
11ce0 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
11cf0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
11d00 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
11d10 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
11d20 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
11d30 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
11d40 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
11d50 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
11d60 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
11d70 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
11d80 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
11d90 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
11da0 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
11db0 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
11dc0 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
11dd0 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
11de0 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
11df0 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
11e00 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
11e10 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
11e20 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
11e30 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
11e40 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
11e50 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
11e60 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
11e70 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
11e80 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
11e90 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
11ea0 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
11eb0 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
11ec0 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
11ed0 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
11ee0 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
11ef0 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
11f00 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
11f10 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
11f20 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
11f30 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
11f40 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
11f50 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
11f60 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
11f70 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
11f80 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
11f90 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
11fa0 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
11fb0 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
11fc0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
11fd0 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
11fe0 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
11ff0 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
12000 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
12010 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
12020 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
12030 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
12040 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
12050 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
12060 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
12070 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
12080 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
12090 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
120a0 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
120b0 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
120c0 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
120d0 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
120e0 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20  as given on the 
120f0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
12100 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
12110 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
12120 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
12130 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
12140 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
12150 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
12160 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
12170 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
12180 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
12190 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
121a0 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
121b0 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
121c0 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
121d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
121e0 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
121f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
12200 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
12210 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12220 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
12230 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
12240 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
12250 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
12260 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
12270 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
12280 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
12290 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
122a0 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
122b0 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
122c0 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
122d0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
122e0 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
122f0 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
12300 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
12310 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
12320 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
12330 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
12340 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
12350 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
12360 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
12370 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
12380 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
12390 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
123a0 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
123b0 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
123c0 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
123d0 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
123e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
123f0 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
12400 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
12410 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
12420 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
12430 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
12440 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
12450 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
12460 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
12470 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
12480 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
12490 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
124a0 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
124b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
124c0 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
124d0 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
124e0 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
124f0 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
12500 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
12510 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
12520 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
12530 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
12540 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
12550 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
12560 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12570 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
12580 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
12590 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
125a0 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
125b0 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
125c0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
125d0 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
125e0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
125f0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
12600 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
12610 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
12620 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
12630 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12640 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
12650 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
12660 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
12670 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
12680 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
12690 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
126a0 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
126b0 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
126c0 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
126d0 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
126e0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
126f0 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
12700 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12710 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
12720 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
12730 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
12740 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
12750 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
12760 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
12770 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
12780 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12790 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
127a0 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
127b0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
127c0 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
127d0 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
127e0 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
127f0 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
12800 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
12810 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
12820 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
12830 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
12840 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
12850 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
12860 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
12870 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
12880 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
12890 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
128a0 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
128b0 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
128c0 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
128d0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
128e0 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
128f0 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
12900 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12910 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
12920 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
12930 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
12940 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12950 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
12960 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
12970 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
12980 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12990 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
129a0 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
129b0 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
129c0 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
129d0 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
129e0 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
129f0 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
12a00 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
12a10 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
12a20 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
12a30 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
12a40 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
12a50 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
12a60 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
12a70 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
12a80 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
12a90 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
12aa0 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
12ab0 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
12ac0 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
12ad0 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
12ae0 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
12af0 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
12b00 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
12b10 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
12b20 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
12b30 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
12b40 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
12b50 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
12b60 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
12b70 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12b80 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
12b90 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
12ba0 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
12bb0 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
12bc0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
12bd0 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
12be0 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
12bf0 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
12c00 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
12c10 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
12c20 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
12c30 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
12c40 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
12c50 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
12c60 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
12c70 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
12c80 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
12c90 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
12ca0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
12cb0 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
12cc0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12cd0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
12ce0 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
12cf0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
12d00 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
12d10 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
12d20 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
12d30 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
12d40 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
12d50 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
12d60 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
12d70 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
12d80 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
12d90 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
12da0 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
12db0 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
12dc0 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
12dd0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
12de0 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
12df0 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
12e00 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
12e10 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
12e20 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
12e30 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
12e40 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
12e50 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
12e60 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
12e70 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
12e80 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
12e90 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
12ea0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
12eb0 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
12ec0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
12ed0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
12ee0 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
12ef0 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
12f00 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
12f10 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
12f20 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
12f30 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
12f40 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
12f50 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
12f60 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
12f70 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
12f80 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
12f90 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
12fa0 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
12fb0 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
12fc0 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
12fd0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
12fe0 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
12ff0 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
13000 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
13010 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
13020 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
13030 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
13040 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
13050 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
13060 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
13070 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
13080 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
13090 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
130a0 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
130b0 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
130c0 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
130d0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
130e0 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
130f0 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
13100 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
13110 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
13120 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
13130 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
13140 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
13150 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
13160 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
13170 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
13180 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
13190 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
131a0 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
131b0 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
131c0 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
131d0 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
131e0 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
131f0 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
13200 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
13210 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
13220 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
13230 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
13240 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
13250 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
13260 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
13270 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
13280 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
13290 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
132a0 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
132b0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
132c0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
132d0 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
132e0 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
132f0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
13300 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
13310 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
13320 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
13330 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
13340 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
13350 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
13360 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
13370 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
13380 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
13390 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
133a0 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ze(void);.SQLITE
133b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
133c0 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
133d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
133e0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
133f0 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
13400 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  I int sqlite3_os
13410 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
13420 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
13430 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
13440 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
13450 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
13460 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
13470 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
13480 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
13490 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
134a0 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
134b0 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
134c0 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
134d0 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
134e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
134f0 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
13500 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
13510 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
13520 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
13530 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
13540 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
13550 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
13560 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
13570 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
13580 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
13590 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
135a0 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 54 68  eds..**.** <b>Th
135b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
135c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
135d0 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20  not threadsafe. 
135e0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
135f0 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74  ** must ensure t
13600 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
13610 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
13620 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
13630 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
13640 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
13650 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
13660 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  .</b>.**.** The 
13670 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13680 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 6d 61   interface.** ma
13690 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
136a0 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
136b0 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
136c0 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
136d0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
136e0 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
136f0 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
13700 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
13710 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
13720 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
13730 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
13740 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
13750 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
13760 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
13770 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
13780 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
13790 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
137a0 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
137b0 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
137c0 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
137d0 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
137e0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
137f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
13800 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
13810 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
13820 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13830 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
13840 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
13850 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72  ger.** [configur
13860 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
13870 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
13880 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
13890 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
138a0 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
138b0 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
138c0 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
138d0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f  nding on the [co
138e0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
138f0 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
13900 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
13910 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
13920 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13930 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
13940 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
13950 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
13960 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
13970 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
13980 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
13990 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
139a0 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
139b0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
139c0 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
139d0 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54   code]..*/.SQLIT
139e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
139f0 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
13a00 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
13a10 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
13a20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13a30 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
13a40 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
13a50 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
13a60 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
13a70 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
13a80 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
13a90 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
13aa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13ab0 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
13ac0 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
13ad0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
13ae0 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
13af0 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
13b00 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
13b10 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
13b20 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
13b30 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
13b40 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a  t argument)..**.
13b50 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
13b60 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
13b70 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c  3_db_config(D,V,
13b80 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20  ...)  is the.** 
13b90 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
13ba0 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e  _LOOKASIDE | con
13bb0 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d  figuration verb]
13bc0 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
13bd0 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  de .** that indi
13be0 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63  cates what aspec
13bf0 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
13c00 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
13c10 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72  s being configur
13c20 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e  ed..** Subsequen
13c30 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79  t arguments vary
13c40 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
13c50 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
13c60 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  verb..**.** ^Cal
13c70 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  ls to sqlite3_db
13c80 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
13c90 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e   SQLITE_OK if an
13ca0 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65  d only if.** the
13cb0 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65   call is conside
13cc0 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a  red successful..
13cd0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
13ce0 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  t sqlite3_db_con
13cf0 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  fig(sqlite3*, in
13d00 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  t op, ...);../*.
13d10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
13d20 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
13d30 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e  outines.**.** An
13d40 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
13d50 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
13d60 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
13d70 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
13d80 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
13d90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13da0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
13db0 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
13dc0 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
13dd0 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
13de0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
13df0 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
13e00 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
13e10 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
13e20 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
13e30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13e40 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
13e50 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13e60 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
13e70 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f  CONFIG_MALLOC] o
13e80 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
13e90 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a  _GETMALLOC].  .*
13ea0 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e  * By creating an
13eb0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
13ec0 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
13ed0 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
13ee0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
13ef0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
13f00 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67  LLOC]).** during
13f10 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
13f20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  an application c
13f30 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
13f40 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
13f50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
13f60 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c  ubsystem for SQL
13f70 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
13f80 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e  ll of its.** dyn
13f90 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
13fa0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
13fb0 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
13fc0 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75  with several [bu
13fd0 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
13fe0 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61  locators].** tha
13ff0 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20  t are perfectly 
14000 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
14010 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
14020 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
14030 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
14040 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
14050 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
14060 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
14070 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
14080 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
14090 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
140a0 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
140b0 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
140c0 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
140d0 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
140e0 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
140f0 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
14100 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
14110 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
14120 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
14130 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
14140 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
14150 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
14160 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
14170 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
14180 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
14190 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
141a0 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
141b0 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64  c, xRealloc, and
141c0 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
141d0 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
141e0 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72  e.** malloc(), r
141f0 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  ealloc() and fre
14200 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  e() functions fr
14210 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
14220 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53  C library..** ^S
14230 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
14240 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
14250 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
14260 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61  xRealloc is alwa
14270 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72  ys a value retur
14280 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63  ned by a prior c
14290 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e  all to xRoundup.
142a0 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
142b0 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
142c0 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
142d0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
142e0 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
142f0 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
14300 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
14310 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
14320 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
14330 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
14340 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
14350 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
14360 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
14370 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
14380 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
14390 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
143a0 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
143b0 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
143c0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
143d0 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
143e0 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
143f0 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
14400 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
14410 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
14420 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
14430 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
14440 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
14450 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
14460 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
14470 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
14480 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
14490 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79  .** Every memory
144a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
144b0 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68  est coming in th
144c0 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d  rough [sqlite3_m
144d0 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b  alloc()].** or [
144e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
144f0 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78  )] first calls x
14500 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f  Roundup.  If xRo
14510 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c  undup returns 0,
14520 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73   .** that causes
14530 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
14540 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ng memory alloca
14550 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a  tion to fail..**
14560 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
14570 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
14580 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
14590 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61 6d  cator.  For exam
145a0 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74  ple,.** it might
145b0 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65   allocate any re
145c0 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72  quire mutexes or
145d0 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65   initialize inte
145e0 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72  rnal data.** str
145f0 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78 53  uctures.  The xS
14600 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
14610 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72  s invoked (indir
14620 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71  ectly) by.** [sq
14630 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
14640 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61  ] and should dea
14650 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f  llocate any reso
14660 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a  urces acquired.*
14670 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65  * by xInit.  The
14680 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65   pAppData pointe
14690 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  r is used as the
146a0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
146b0 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20  to.** xInit and 
146c0 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a  xShutdown..**.**
146d0 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68   SQLite holds th
146e0 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
146f0 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d  STATIC_MASTER] m
14700 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76  utex when it inv
14710 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69  okes.** the xIni
14720 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65  t method, so the
14730 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65   xInit method ne
14740 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64  ed not be thread
14750 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53  safe.  The.** xS
14760 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69  hutdown method i
14770 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72  s only called fr
14780 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  om [sqlite3_shut
14790 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f  down()] so it do
147a0 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74  es.** not need t
147b0 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  o be threadsafe 
147c0 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c  either.  For all
147d0 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20   other methods, 
147e0 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20  SQLite.** holds 
147f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
14800 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75  X_STATIC_MEM] mu
14810 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  tex as long as t
14820 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  he.** [SQLITE_CO
14830 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
14840 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14850 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
14860 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69  n (which.** it i
14870 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e  s by default) an
14880 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73  d so the methods
14890 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
148a0 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a  ly serialized..*
148b0 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53  * However, if [S
148c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
148d0 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61 62  STATUS] is disab
148e0 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74  led, then the ot
148f0 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d  her.** methods m
14900 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
14910 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74  e or else make t
14920 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65  heir own arrange
14930 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72  ments for.** ser
14940 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ialization..**.*
14950 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65  * SQLite will ne
14960 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74  ver invoke xInit
14970 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  () more than onc
14980 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74  e without an int
14990 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c  ervening.** call
149a0 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e   to xShutdown().
149b0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
149c0 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
149d0 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d  ethods sqlite3_m
149e0 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  em_methods;.stru
149f0 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ct sqlite3_mem_m
14a00 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20  ethods {.  void 
14a10 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29  *(*xMalloc)(int)
14a20 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d  ;         /* Mem
14a30 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
14a40 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  unction */.  voi
14a50 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a  d (*xFree)(void*
14a60 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46  );          /* F
14a70 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f  ree a prior allo
14a80 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64  cation */.  void
14a90 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f   *(*xRealloc)(vo
14aa0 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65  id*,int);  /* Re
14ab0 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69  size an allocati
14ac0 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  on */.  int (*xS
14ad0 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ize)(void*);    
14ae0 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e         /* Return
14af0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20   the size of an 
14b00 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
14b10 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28  int (*xRoundup)(
14b20 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f  int);          /
14b30 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65  * Round up reque
14b40 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63  st size to alloc
14b50 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20  ation size */.  
14b60 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69  int (*xInit)(voi
14b70 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
14b80 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  * Initialize the
14b90 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
14ba0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53  r */.  void (*xS
14bb0 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b  hutdown)(void*);
14bc0 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69        /* Deiniti
14bd0 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
14be0 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
14bf0 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20  void *pAppData; 
14c00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
14c10 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49  * Argument to xI
14c20 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74 64  nit() and xShutd
14c30 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  own() */.};../*.
14c40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
14c50 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
14c60 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
14c70 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  {configuration o
14c80 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  ption}.**.** The
14c90 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
14ca0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
14cb0 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
14cc0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
14cd0 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
14ce0 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ed as the first 
14cf0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
14d00 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
14d10 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  )] interface..**
14d20 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72  .** New configur
14d30 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61  ation options ma
14d40 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
14d50 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
14d60 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73   SQLite..** Exis
14d70 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ting configurati
14d80 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74  on options might
14d90 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64   be discontinued
14da0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a  .  Applications.
14db0 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20  ** should check 
14dc0 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
14dd0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
14de0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
14df0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
14e00 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54   call worked.  T
14e10 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
14e20 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
14e30 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
14e40 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
14e50 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
14e60 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
14e70 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
14e80 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
14e90 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
14ea0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
14eb0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
14ec0 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
14ed0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
14ee0 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ETHREAD</dt>.** 
14ef0 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
14f00 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
14f10 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
14f20 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
14f30 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
14f40 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d  mode] to Single-
14f50 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
14f60 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
14f70 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
14f80 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51  xing and puts SQ
14f90 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65  Lite into a mode
14fa0 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e   where it can on
14fb0 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79  ly be used.** by
14fc0 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64   a single thread
14fd0 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
14fe0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
14ff0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
15000 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
15010 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
15020 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
15030 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
15040 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
15050 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74  to change the [t
15060 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66  hreading mode] f
15070 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a  rom its default.
15080 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67  ** value of Sing
15090 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f  le-thread and so
150a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
150b0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
150c0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  .** [SQLITE_ERRO
150d0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
150e0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
150f0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
15100 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
15110 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
15120 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15130 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
15140 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15150 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
15160 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
15170 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
15180 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
15190 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
151a0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
151b0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
151c0 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20  o Multi-thread. 
151d0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
151e0 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
151f0 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74  mutexing on [dat
15200 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15210 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
15220 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
15230 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ts..** The appli
15240 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e  cation is respon
15250 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c  sible for serial
15260 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a  izing access to.
15270 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
15280 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
15290 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
152a0 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20  ts].  But other 
152b0 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
152c0 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53  nabled so that S
152d0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61  QLite will be sa
152e0 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d  fe to use in a m
152f0 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ulti-threaded.**
15300 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20   environment as 
15310 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74  long as no two t
15320 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20 74  hreads attempt t
15330 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a  o use the same.*
15340 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
15350 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73  ection] at the s
15360 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53  ame time.  ^If S
15370 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
15380 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
15390 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
153a0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
153b0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
153c0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
153d0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
153e0 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
153f0 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b  e Multi-thread [
15400 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
15410 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
15420 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
15430 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
15440 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
15450 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
15460 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
15470 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69  READ configurati
15480 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
15490 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
154a0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
154b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
154c0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c  NFIG_SERIALIZED<
154d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
154e0 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
154f0 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
15500 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
15510 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
15520 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
15530 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20   Serialized. In 
15540 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69  other words, thi
15550 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73  s option enables
15560 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20  .** all mutexes 
15570 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65  including the re
15580 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78  cursive.** mutex
15590 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  es on [database 
155a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
155b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
155c0 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
155d0 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77   In this mode (w
155e0 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66 61  hich is the defa
155f0 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20  ult when SQLite 
15600 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
15610 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
15620 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53  ADSAFE=1]) the S
15630 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69  QLite library wi
15640 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c  ll itself serial
15650 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ize access.** to
15660 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
15670 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
15680 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
15690 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a  ] so that the.**
156a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
156b0 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65 20  free to use the 
156c0 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
156d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68  onnection] or th
156e0 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61  e.** same [prepa
156f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
15700 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  n different thre
15710 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
15720 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c  time..** ^If SQL
15730 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
15740 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
15750 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
15760 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
15770 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
15780 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
15790 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
157a0 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
157b0 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  Serialized [thre
157c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
157d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
157e0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
157f0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
15800 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
15810 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
15820 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
15830 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15840 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
15850 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15860 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  _MALLOC]] <dt>SQ
15870 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
15880 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
15890 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
158a0 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f  FIG_MALLOC optio
158b0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
158c0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
158d0 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
158e0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
158f0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
15900 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
15910 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
15920 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
15930 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
15940 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
15950 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
15960 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
15970 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   in place of.** 
15980 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
15990 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62  ation routines b
159a0 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
159b0 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  .)^ ^SQLite make
159c0 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69  s.** its own pri
159d0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
159e0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
159f0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
15a00 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a  hods] structure.
15a10 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73  ** before the [s
15a20 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15a30 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f   call returns.</
15a40 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15a50 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
15a60 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
15a70 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
15a80 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
15a90 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15aa0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f 70 74  IG_GETMALLOC opt
15ab0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15ac0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
15ad0 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65  h.** is a pointe
15ae0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
15af0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
15b00 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
15b10 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20  ructure..** The 
15b20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
15b30 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
15b40 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
15b50 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
15b60 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61  defined memory a
15b70 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
15b80 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70  es.)^.** This op
15b90 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64  tion can be used
15ba0 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65   to overload the
15bb0 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
15bc0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f  allocation.** ro
15bd0 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72  utines with a wr
15be0 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c  apper that simul
15bf0 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c  ations memory al
15c00 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
15c10 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65   or.** tracks me
15c20 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20  mory usage, for 
15c30 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a  example. </dd>.*
15c40 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15c50 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d  NFIG_MEMSTATUS]]
15c60 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15c70 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74  IG_MEMSTATUS</dt
15c80 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
15c90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
15ca0 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20 74 61  STATUS option ta
15cb0 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  kes single argum
15cc0 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c  ent of type int,
15cd0 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65 64 20  .** interpreted 
15ce0 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20 77 68  as a boolean, wh
15cf0 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
15d00 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
15d10 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d  ection of.** mem
15d20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
15d30 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65  tatistics. ^(Whe
15d40 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
15d50 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
15d60 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2c 20  re.** disabled, 
15d70 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
15d80 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
15d90 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
15da0 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
15db0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
15dc0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
15dd0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
15de0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
15df0 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
15e00 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
15e10 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
15e20 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
15e30 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34 28 29  lite3_status64()
15e40 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
15e50 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
15e60 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
15e70 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
15e80 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
15e90 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
15ea0 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
15eb0 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
15ec0 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
15ed0 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
15ee0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
15ef0 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
15f00 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
15f10 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15f20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
15f30 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TCH]] <dt>SQLITE
15f40 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c  _CONFIG_SCRATCH<
15f50 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
15f60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15f70 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e 20 73  SCRATCH option s
15f80 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
15f90 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 0a  c memory buffer.
15fa0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  ** that SQLite c
15fb0 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72 61 74  an use for scrat
15fc0 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28 54 68  ch memory.  ^(Th
15fd0 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
15fe0 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20 53 51  guments.** to SQ
15ff0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
16000 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  TCH:  A pointer 
16010 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
16020 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
16030 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
16040 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
16050 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
16060 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
16070 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
16080 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
16090 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
160a0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
160b0 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
160c0 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65  ns (N).)^.** The
160d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
160e0 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65  must be a pointe
160f0 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61  r to an 8-byte a
16100 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a  ligned buffer.**
16110 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
16120 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
16130 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
16140 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72 65 20  ll not use more 
16150 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74 63 68  than one scratch
16160 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72   buffers per thr
16170 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ead..** ^SQLite 
16180 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 65  will never reque
16190 73 74 20 61 20 73 63 72 61 74 63 68 20 62 75 66  st a scratch buf
161a0 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
161b0 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73   than 6.** times
161c0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
161d0 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  ge size..** ^If 
161e0 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
161f0 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
16200 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
16210 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
16220 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
16230 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16240 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
16250 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16260 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
16270 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
16280 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a  ory needed.<p>.*
16290 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70 70 6c  * ^When the appl
162a0 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64 65 73  ication provides
162b0 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66 20 73   any amount of s
162c0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 75 73  cratch memory us
162d0 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  ing.** SQLITE_CO
162e0 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20 53 51  NFIG_SCRATCH, SQ
162f0 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e 6e 65  Lite avoids unne
16300 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a 2a 2a  cessary large.**
16310 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
16320 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69 6f 6e  |heap allocation
16330 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61 6e 20  s]..** This can 
16340 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70 72 6f  help [Robson pro
16350 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d 6f 72  of|prevent memor
16360 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
16370 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20 68 65  lures] due to he
16380 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74 61 74  ap.** fragmentat
16390 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72  ion in low-memor
163a0 79 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  y embedded syste
163b0 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ms..** </dd>.**.
163c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
163d0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c  IG_PAGECACHE]] <
163e0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
163f0 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
16400 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
16410 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
16420 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70 65 63  ACHE option spec
16430 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79 20 70  ifies a memory p
16440 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69  ool.** that SQLi
16450 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74  te can use for t
16460 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
16470 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
16480 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20  default page.** 
16490 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
164a0 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
164b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
164c0 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f 70 20  tion is a no-op 
164d0 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
164e0 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a  n-define page.**
164f0 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
16500 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20  ation is loaded 
16510 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
16520 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
16530 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65  ]..** ^There are
16540 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
16550 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
16560 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41 20 70  G_PAGECACHE: A p
16570 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62  ointer to.** 8-b
16580 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f  yte aligned memo
16590 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65 20 73  ry (pMem), the s
165a0 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
165b0 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73 7a 29   cache line (sz)
165c0 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e 75 6d  ,.** and the num
165d0 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c 69 6e  ber of cache lin
165e0 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
165f0 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
16600 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
16610 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
16620 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
16630 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
16640 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 36 35  tween 512 and 65
16650 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65 20 65  536) plus some e
16660 78 74 72 61 20 62 79 74 65 73 20 66 6f 72 20 65  xtra bytes for e
16670 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
16680 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62 65 72  er.  ^The number
16690 20 6f 66 20 65 78 74 72 61 20 62 79 74 65 73 20   of extra bytes 
166a0 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 70 61  needed by the pa
166b0 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63 61 6e  ge header.** can
166c0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
166d0 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  sing [SQLITE_CON
166e0 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
166f0 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61 72  ]..** ^It is har
16700 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
16710 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
16720 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ory,.** for the 
16730 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  sz parameter to 
16740 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20 6e  be larger than n
16750 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20 70  ecessary.  The p
16760 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  Mem.** argument 
16770 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
16780 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
16790 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
167a0 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
167b0 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f  ed block of memo
167c0 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ry of at least s
167d0 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68 65 72  z*N bytes, other
167e0 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71 75 65  wise.** subseque
167f0 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  nt behavior is u
16800 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68  ndefined..** ^Wh
16810 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74 20 4e  en pMem is not N
16820 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
16830 20 73 74 72 69 76 65 20 74 6f 20 75 73 65 20 74   strive to use t
16840 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
16850 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73 66 79  ed.** to satisfy
16860 20 70 61 67 65 20 63 61 63 68 65 20 6e 65 65 64   page cache need
16870 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63 6b 20  s, falling back 
16880 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
16890 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20 70 61  oc()] if.** a pa
168a0 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 69 73  ge cache line is
168b0 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73 7a 20   larger than sz 
168c0 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c 6c 20  bytes or if all 
168d0 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75 66 66  of the pMem buff
168e0 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75 73 74  er.** is exhaust
168f0 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65 6d 20  ed..** ^If pMem 
16900 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73  is NULL and N is
16910 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
16920 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
16930 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73  nnection.** does
16940 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75 6c 6b   an initial bulk
16950 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
16960 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
16970 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  y.** from [sqlit
16980 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 75 66  e3_malloc()] suf
16990 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20 63 61  ficient for N ca
169a0 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e 20 69  che lines if N i
169b0 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a 2a 2a  s positive or.**
169c0 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79 74 65   of -1024*N byte
169d0 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61 74 69  s if N is negati
169e0 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69 74 69  ve, . ^If additi
169f0 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
16a00 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
16a10 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
16a20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
16a30 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c  he initial.** al
16a40 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 53  location, then S
16a50 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73  QLite goes to [s
16a60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16a70 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f 72 20   separately for 
16a80 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69 6f 6e  each.** addition
16a90 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e 20 3c  al cache line. <
16aa0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16ab0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
16ac0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16ad0 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
16ae0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
16af0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70  E_CONFIG_HEAP op
16b00 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
16b10 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
16b20 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74 20 53  uffer .** that S
16b30 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 66  QLite will use f
16b40 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
16b50 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
16b60 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a  ocation needs.**
16b70 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
16b80 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20 5b 53  ovided for by [S
16b90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
16ba0 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51  ATCH] and.** [SQ
16bb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
16bc0 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20  CACHE]..** ^The 
16bd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
16be0 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  AP option is onl
16bf0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53  y available if S
16c00 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
16c10 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68 65 72  d.** with either
16c20 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
16c30 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53 51 4c  MEMSYS3] or [SQL
16c40 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
16c50 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  S5] and returns.
16c60 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
16c70 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f 74 68  ] if invoked oth
16c80 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68 65 72  erwise..** ^Ther
16c90 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
16ca0 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54 45 5f  ments to SQLITE_
16cb0 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a 2a 20  CONFIG_HEAP:.** 
16cc0 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
16cd0 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
16ce0 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
16cf0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
16d00 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
16d10 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
16d20 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
16d30 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
16d40 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
16d50 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
16d60 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
16d70 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
16d80 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
16d90 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
16da0 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
16db0 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
16dc0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
16dd0 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
16de0 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
16df0 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
16e00 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
16e10 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
16e20 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
16e30 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  LL then the alte
16e40 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
16e50 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
16e60 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
16e70 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
16e80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
16e90 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
16ea0 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
16eb0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
16ec0 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
16ed0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
16ee0 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
16ef0 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
16f00 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
16f10 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a  l be undefined..
16f20 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61  ** The minimum a
16f30 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69  llocation size i
16f40 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31  s capped at 2**1
16f50 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61  2. Reasonable va
16f60 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  lues.** for the 
16f70 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
16f80 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35  on size are 2**5
16f90 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f   through 2**8.</
16fa0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16fb0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
16fc0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16fd0 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
16fe0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
16ff0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
17000 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17010 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
17020 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20 70 6f  which is a.** po
17030 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
17040 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
17050 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
17060 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a  ds] structure..*
17070 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73  * The argument s
17080 70 65 63 69 66 69 65 73 20 61 6c 74 65 72 6e 61  pecifies alterna
17090 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
170a0 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f  utex routines to
170b0 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e 20 70   be used.** in p
170c0 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78 20 72  lace the mutex r
170d0 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
170e0 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53  to SQLite.)^  ^S
170f0 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
17100 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
17110 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
17120 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
17130 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65  ds] structure be
17140 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f  fore the call to
17150 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
17160 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20  fig()] returns. 
17170 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
17180 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
17190 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
171a0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
171b0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
171c0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
171d0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74   then.** the ent
171e0 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62  ire mutexing sub
171f0 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65  system is omitte
17200 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64  d from the build
17210 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73   and hence calls
17220 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
17230 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74  config()] with t
17240 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
17250 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  _MUTEX configura
17260 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
17270 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
17280 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
17290 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
172a0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d  ONFIG_GETMUTEX]]
172b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
172c0 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e  IG_GETMUTEX</dt>
172d0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
172e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
172f0 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b  MUTEX option tak
17300 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
17310 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
17320 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
17330 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
17340 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
17350 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
17360 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
17370 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
17380 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
17390 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
173a0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
173b0 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
173c0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
173d0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
173e0 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
173f0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
17400 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
17410 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
17420 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
17430 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
17440 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
17450 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
17460 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
17470 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
17480 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
17490 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
174a0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
174b0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
174c0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
174d0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
174e0 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
174f0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
17500 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
17510 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
17520 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
17530 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
17540 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
17550 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
17560 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
17570 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
17580 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
17590 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
175a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
175b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
175c0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
175d0 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
175e0 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
175f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
17600 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61 6b 65  SIDE option take
17610 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
17620 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 0a 2a  that determine.*
17630 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20 73 69  * the default si
17640 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20  ze of lookaside 
17650 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68 20 5b  memory on each [
17660 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17670 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ion]..** The fir
17680 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  st argument is t
17690 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61  he.** size of ea
176a0 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ch lookaside buf
176b0 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65  fer slot and the
176c0 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e   second is the n
176d0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
176e0 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65  s allocated to e
176f0 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
17700 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 53 51  nection.)^  ^(SQ
17710 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
17720 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20 74 68  ASIDE.** sets th
17730 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  e <i>default</i>
17740 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
17750 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
17760 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
17770 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20 5b 73  .** option to [s
17780 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
17790 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20  ()] can be used 
177a0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
177b0 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69  okaside.** confi
177c0 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  guration on indi
177d0 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f  vidual connectio
177e0 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ns.)^ </dd>.**.*
177f0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17800 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  G_PCACHE2]] <dt>
17810 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
17820 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
17830 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
17840 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
17850 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
17860 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
17870 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69  ich is .** a poi
17880 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69  nter to an [sqli
17890 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
178a0 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68  ds2] object.  Th
178b0 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66  is object specif
178c0 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74 65 72  ies.** the inter
178d0 66 61 63 65 20 74 6f 20 61 20 63 75 73 74 6f 6d  face to a custom
178e0 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
178f0 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  ementation.)^.**
17900 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
17910 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
17920 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
17930 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f  hods2] object.</
17940 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
17950 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
17960 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
17970 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
17980 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
17990 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
179a0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
179b0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
179c0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
179d0 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
179e0 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71 6c 69  nter to an [sqli
179f0 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
17a00 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ds2] object.  SQ
17a10 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 0a 2a  Lite copies of.*
17a20 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20 70 61  * the current pa
17a30 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
17a40 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
17a50 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64  t object.)^ </dd
17a60 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
17a70 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64  _CONFIG_LOG]] <d
17a80 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17a90 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOG</dt>.** <dd>
17aa0 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   The SQLITE_CONF
17ab0 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 69 73  IG_LOG option is
17ac0 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
17ad0 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a 2a 2a  re the SQLite.**
17ae0 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72 20 6c   global [error l
17af0 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20 53 51  og]..** (^The SQ
17b00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
17b10 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
17b20 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
17b30 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
17b40 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
17b50 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
17b60 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
17b70 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
17b80 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
17b90 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
17ba0 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
17bb0 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
17bc0 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
17bd0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
17be0 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
17bf0 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
17c00 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
17c10 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
17c20 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
17c30 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
17c40 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
17c50 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
17c60 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
17c70 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
17c80 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
17c90 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
17ca0 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
17cb0 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
17cc0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
17cd0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
17ce0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
17cf0 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
17d00 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
17d10 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
17d20 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17d30 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
17d40 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
17d50 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
17d60 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
17d70 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
17d80 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
17d90 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
17da0 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
17db0 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
17dc0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
17dd0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
17de0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
17df0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
17e00 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
17e10 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
17e20 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
17e30 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
17e40 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
17e50 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
17e60 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
17e70 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
17e80 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
17e90 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
17ea0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
17eb0 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
17ec0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
17ed0 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
17ee0 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
17ef0 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
17f00 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
17f10 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
17f20 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
17f30 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
17f40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17f50 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51  FIG_URI]] <dt>SQ
17f60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a  LITE_CONFIG_URI.
17f70 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53 51 4c  ** <dd>^(The SQL
17f80 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 6f  ITE_CONFIG_URI o
17f90 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
17fa0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
17fb0 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20 49 66   type int..** If
17fc0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
17fd0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
17fe0 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
17ff0 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
18000 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74  er is zero,.** t
18010 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
18020 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
18030 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52 49  abled.)^ ^If URI
18040 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
18050 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c 65 64  bally.** enabled
18060 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 20  , all filenames 
18070 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74  passed to [sqlit
18080 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
18090 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
180a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
180b0 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65  n16()] or.** spe
180c0 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
180d0 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61  f [ATTACH] comma
180e0 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  nds are interpre
180f0 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67  ted as URIs, reg
18100 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68  ardless.** of wh
18110 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
18120 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
18130 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  I] flag is set w
18140 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
18150 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
18160 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74  s opened. ^If it
18170 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
18180 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73  abled, filenames
18190 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74   are.** only int
181a0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
181b0 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f   if the SQLITE_O
181c0 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20  PEN_URI flag is 
181d0 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  set when the.** 
181e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
181f0 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
18200 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49  (By default, URI
18210 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
18220 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
18230 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
18240 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
18250 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
18260 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
18270 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
18280 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a  mbol defined.)^.
18290 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
182a0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
182b0 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e  NDEX_SCAN]] <dt>
182c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
182d0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
182e0 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51  N.** <dd>^The SQ
182f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
18300 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
18310 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
18320 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a 2a 2a  ingle integer.**
18330 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
18340 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
18350 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f  s a boolean in o
18360 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f  rder to enable o
18370 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  r disable.** the
18380 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
18390 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c   indices for ful
183a0 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e  l table scans in
183b0 20 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d   the query optim
183c0 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  izer..** ^The de
183d0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73  fault setting is
183e0 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62   determined.** b
183f0 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c  y the [SQLITE_AL
18400 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  LOW_COVERING_IND
18410 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65  EX_SCAN] compile
18420 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72  -time option, or
18430 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74   is "on".** if t
18440 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  hat compile-time
18450 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74   option is omitt
18460 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69  ed..** The abili
18470 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68  ty to disable th
18480 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
18490 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
184a0 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a  ll table scans.*
184b0 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d  * is because som
184c0 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f  e incorrectly co
184d0 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69  ded legacy appli
184e0 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61  cations might ma
184f0 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65  lfunction.** whe
18500 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  n the optimizati
18510 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20  on is enabled.  
18520 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62  Providing the ab
18530 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61  ility to.** disa
18540 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  ble the optimiza
18550 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20  tion allows the 
18560 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70  older, buggy app
18570 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f  lication code to
18580 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74   work.** without
18590 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74   change even wit
185a0 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  h newer versions
185b0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
185c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
185d0 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
185e0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
185f0 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
18600 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
18610 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
18620 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a  NFIG_GETPCACHE.*
18630 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74  * <dd> These opt
18640 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74  ions are obsolet
18650 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74  e and should not
18660 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20   be used by new 
18670 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72  code..** They ar
18680 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
18690 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
186a0 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e  bility but are n
186b0 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f  ow no-ops..** </
186c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
186d0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
186e0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
186f0 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a  _CONFIG_SQLLOG.*
18700 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
18710 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
18720 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73  ble if sqlite is
18730 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
18740 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
18750 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65  ABLE_SQLLOG] pre
18760 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
18770 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
18780 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
18790 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
187a0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
187b0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
187c0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
187d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
187e0 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
187f0 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
18800 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
18810 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
18820 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
18830 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
18840 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
18850 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
18860 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
18870 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
18880 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
18890 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
188a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
188b0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
188c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
188d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
188e0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
188f0 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
18900 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
18910 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
18920 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
18930 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
18940 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
18950 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
18960 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
18970 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
18980 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
18990 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
189a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
189b0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
189c0 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
189d0 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
189e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
189f0 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
18a00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
18a10 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
18a20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18a30 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
18a40 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
18a50 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
18a60 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
18a70 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c  case.  An exampl
18a80 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a  e of using this.
18a90 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
18aa0 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73   option can be s
18ab0 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74  een in the "test
18ac0 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63  _sqllog.c" sourc
18ad0 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65  e file in.** the
18ae0 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74   canonical SQLit
18af0 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f  e source tree.</
18b00 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
18b10 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
18b20 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
18b30 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
18b40 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c  SIZE.** <dd>^SQL
18b50 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
18b60 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36  SIZE takes two 6
18b70 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73  4-bit integer (s
18b80 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61  qlite3_int64) va
18b90 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  lues.** that are
18ba0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61   the default mma
18bb0 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68  p size limit (th
18bc0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
18bd0 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41  g for.** [PRAGMA
18be0 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64   mmap_size]) and
18bf0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c   the maximum all
18c00 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c  owed mmap size l
18c10 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  imit..** ^The de
18c20 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61  fault setting ca
18c30 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20  n be overridden 
18c40 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65  by each database
18c50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e   connection usin
18c60 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20  g.** either the 
18c70 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
18c80 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62  e] command, or b
18c90 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  y using the.** [
18ca0 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
18cb0 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
18cc0 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78  trol.  ^(The max
18cd0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
18ce0 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62  p size.** will b
18cf0 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  e silently trunc
18d00 61 74 65 64 20 69 66 20 6e 65 63 65 73 73 61 72  ated if necessar
18d10 79 20 73 6f 20 74 68 61 74 20 69 74 20 64 6f 65  y so that it doe
18d20 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74 68 65  s not exceed the
18d30 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
18d40 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69   maximum mmap si
18d50 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a  ze set by the.**
18d60 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41   [SQLITE_MAX_MMA
18d70 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d  P_SIZE] compile-
18d80 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a  time option.)^.*
18d90 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61 72 67  * ^If either arg
18da0 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70  ument to this op
18db0 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65  tion is negative
18dc0 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72 67 75  , then that argu
18dd0 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67  ment is.** chang
18de0 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c  ed to its compil
18df0 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a  e-time default..
18e00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
18e10 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
18e20 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  SIZE]].** <dt>SQ
18e30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
18e40 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64  2_HEAPSIZE.** <d
18e50 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
18e60 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
18e70 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  IZE option is on
18e80 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
18e90 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
18ea0 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77  piled for Window
18eb0 73 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  s with the [SQLI
18ec0 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d  TE_WIN32_MALLOC]
18ed0 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
18ee0 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65 64 2e  acro.** defined.
18ef0 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   ^SQLITE_CONFIG_
18f00 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 74  WIN32_HEAPSIZE t
18f10 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75 6e  akes a 32-bit un
18f20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 76  signed integer v
18f30 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70 65  alue.** that spe
18f40 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69 6d  cifies the maxim
18f50 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20 63  um size of the c
18f60 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a 0a  reated heap..**.
18f70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
18f80 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 5d  IG_PCACHE_HDRSZ]
18f90 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
18fa0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
18fb0 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  RSZ.** <dd>^The 
18fc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
18fd0 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74 69 6f  ACHE_HDRSZ optio
18fe0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
18ff0 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68   parameter which
19000 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
19010 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61   to an integer a
19020 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f 20 74  nd writes into t
19030 68 61 74 20 69 6e 74 65 67 65 72 20 74 68 65 20  hat integer the 
19040 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 0a  number of extra.
19050 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70 61 67  ** bytes per pag
19060 65 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 65  e required for e
19070 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53 51 4c  ach page in [SQL
19080 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
19090 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d  ACHE]..** The am
190a0 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20 73 70  ount of extra sp
190b0 61 63 65 20 72 65 71 75 69 72 65 64 20 63 61 6e  ace required can
190c0 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64 69 6e   change dependin
190d0 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  g on the compile
190e0 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70 6c 61  r,.** target pla
190f0 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c 69 74  tform, and SQLit
19100 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  e version..**.**
19110 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
19120 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e  _PMASZ]].** <dt>
19130 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
19140 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  ASZ.** <dd>^The 
19150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d  SQLITE_CONFIG_PM
19160 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  ASZ option takes
19170 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
19180 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
19190 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  an unsigned inte
191a0 67 65 72 20 61 6e 64 20 73 65 74 73 20 74 68 65  ger and sets the
191b0 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69   "Minimum PMA Si
191c0 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75 6c 74  ze" for the mult
191d0 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73 6f 72  ithreaded.** sor
191e0 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e 74 65  ter to that inte
191f0 67 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ger.  The defaul
19200 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20 53 69  t minimum PMA Si
19210 7a 65 20 69 73 20 73 65 74 20 62 79 20 74 68 65  ze is set by the
19220 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f 52 54  .** [SQLITE_SORT
19230 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c  ER_PMASZ] compil
19240 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 20 20  e-time option.  
19250 4e 65 77 20 74 68 72 65 61 64 73 20 61 72 65 20  New threads are 
19260 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f 20 68  launched.** to h
19270 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20 6f 70  elp with sort op
19280 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20 6d 75  erations when mu
19290 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f 72 74  ltithreaded sort
192a0 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62 6c 65  ing.** is enable
192b0 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b 50 52  d (using the [PR
192c0 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20 63 6f  AGMA threads] co
192d0 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65 20 61  mmand) and the a
192e0 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 6e 74  mount of content
192f0 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74 65 64  .** to be sorted
19300 20 65 78 63 65 65 64 73 20 74 68 65 20 70 61 67   exceeds the pag
19310 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74 68 65  e size times the
19320 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68 65 0a   minimum of the.
19330 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63 68 65  ** [PRAGMA cache
19340 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67 20 61  _size] setting a
19350 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e 0a 2a  nd this value..*
19360 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
19370 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50  NFIG_STMTJRNL_SP
19380 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  ILL]].** <dt>SQL
19390 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
193a0 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64  RNL_SPILL.** <dd
193b0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
193c0 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
193d0 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  LL option takes 
193e0 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74  a single paramet
193f0 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65 63 6f  er which.** beco
19400 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65 6d 65  mes the [stateme
19410 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70 69 6c  nt journal] spil
19420 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65 73 68  l-to-disk thresh
19430 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61 74 65  old.  .** [State
19440 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d 20 61  ment journals] a
19450 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  re held in memor
19460 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20 73 69  y until their si
19470 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a 2a 2a  ze (in bytes).**
19480 20 65 78 63 65 65 64 73 20 74 68 69 73 20 74 68   exceeds this th
19490 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68 69 63  reshold, at whic
194a0 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61 72 65  h point they are
194b0 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
194c0 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65 20 74  ..** Or if the t
194d0 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31 2c 20  hreshold is -1, 
194e0 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61  statement journa
194f0 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20 68 65  ls are always he
19500 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76 65 6c  ld.** exclusivel
19510 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  y in memory..** 
19520 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61 74 65  Since many state
19530 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 6e 65  ment journals ne
19540 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72 67 65  ver become large
19550 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20 73 70  , setting the sp
19560 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f 6c 64  ill.** threshold
19570 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75 63 68   to a value such
19580 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20 67 72   as 64KiB can gr
19590 65 61 74 6c 79 20 72 65 64 75 63 65 20 74 68 65  eatly reduce the
195a0 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f   amount of.** I/
195b0 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20 73 75  O required to su
195c0 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e 74 20  pport statement 
195d0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  rollback..** The
195e0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 66   default value f
195f0 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e 67 20  or this setting 
19600 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  is controlled by
19610 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
19620 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20  STMTJRNL_SPILL] 
19630 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
19640 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  ion..** </dl>.*/
19650 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19660 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
19670 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
19680 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19690 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
196a0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
196b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
196c0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
196d0 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
196e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
196f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
19700 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
19710 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
19720 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
19730 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
19740 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
19750 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
19760 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
19770 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
19780 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
19790 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
197a0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
197b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
197c0 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
197d0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
197e0 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
197f0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
19800 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
19810 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
19820 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
19830 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19840 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
19850 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
19860 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
19870 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
19880 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
19890 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
198a0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
198b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
198c0 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
198d0 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
198e0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
198f0 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
19900 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
19910 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
19920 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
19930 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
19940 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
19950 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
19960 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
19970 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
19980 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
19990 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
199a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
199b0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
199c0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
199d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
199e0 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
199f0 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
19a00 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
19a10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
19a20 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
19a30 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
19a40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
19a50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
19a60 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
19a70 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
19a80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
19a90 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
19aa0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
19ab0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
19ac0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
19ad0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
19ae0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
19af0 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
19b00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19b10 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
19b20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
19b30 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
19b40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
19b50 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
19b60 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
19b70 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
19b80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19b90 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
19ba0 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
19bb0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
19bc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19bd0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
19be0 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f  RSZ        24  /
19bf0 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64  * int *psz */.#d
19c00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
19c10 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20  FIG_PMASZ       
19c20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75          25  /* u
19c30 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d  nsigned int szPm
19c40 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  a */.#define SQL
19c50 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d 54 4a  ITE_CONFIG_STMTJ
19c60 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20 20 32  RNL_SPILL      2
19c70 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  6  /* int nByte 
19c80 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
19c90 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
19ca0 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
19cb0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
19cc0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
19cd0 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
19ce0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
19cf0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
19d00 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
19d10 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
19d20 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
19d30 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
19d40 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
19d50 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
19d60 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
19d70 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
19d80 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
19d90 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
19da0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
19db0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
19dc0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
19dd0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
19de0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
19df0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
19e00 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
19e10 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
19e20 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
19e30 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
19e40 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
19e50 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
19e60 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
19e70 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
19e80 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
19e90 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
19ea0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
19eb0 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
19ec0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
19ed0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
19ee0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
19ef0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19f00 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
19f10 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
19f20 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
19f30 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
19f40 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
19f50 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
19f60 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
19f70 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
19f80 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
19f90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19fa0 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
19fb0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
19fc0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
19fd0 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
19fe0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
19ff0 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
1a000 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
1a010 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
1a020 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
1a030 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1a040 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
1a050 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
1a060 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
1a070 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
1a080 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
1a090 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
1a0a0 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
1a0b0 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
1a0c0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
1a0d0 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
1a0e0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
1a0f0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
1a100 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
1a110 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
1a120 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
1a130 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
1a140 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
1a150 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
1a160 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
1a170 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
1a180 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
1a190 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
1a1a0 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
1a1b0 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
1a1c0 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
1a1d0 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
1a1e0 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
1a1f0 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
1a200 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
1a210 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
1a220 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
1a230 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
1a240 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
1a250 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
1a260 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
1a270 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
1a280 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
1a290 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
1a2a0 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
1a2b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
1a2c0 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
1a2d0 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
1a2e0 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
1a2f0 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
1a300 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
1a310 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
1a320 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
1a330 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
1a340 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
1a350 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
1a360 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
1a370 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
1a380 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
1a390 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
1a3a0 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
1a3b0 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
1a3c0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
1a3d0 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
1a3e0 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
1a3f0 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
1a400 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
1a410 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
1a420 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
1a430 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
1a440 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
1a450 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1a460 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1a470 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
1a480 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
1a490 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
1a4a0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
1a4b0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
1a4c0 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
1a4d0 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
1a4e0 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
1a4f0 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
1a500 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
1a510 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
1a520 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
1a530 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
1a540 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
1a550 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
1a560 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
1a570 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
1a580 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
1a590 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
1a5a0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
1a5b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1a5c0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
1a5d0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
1a5e0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
1a5f0 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
1a600 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
1a610 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
1a620 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
1a630 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
1a640 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
1a650 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
1a660 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1a670 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
1a680 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
1a690 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
1a6a0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
1a6b0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
1a6c0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
1a6d0 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
1a6e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
1a6f0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
1a700 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
1a710 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
1a720 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
1a730 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
1a740 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
1a750 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
1a760 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
1a770 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
1a780 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
1a790 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
1a7a0 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
1a7b0 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
1a7c0 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
1a7d0 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
1a7e0 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
1a7f0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
1a800 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
1a810 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
1a820 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
1a830 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
1a840 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
1a850 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
1a860 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
1a870 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
1a880 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
1a890 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
1a8a0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
1a8b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
1a8c0 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
1a8d0 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
1a8e0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
1a8f0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
1a900 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1a910 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
1a920 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f  FTS3_TOKENIZER</
1a930 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
1a940 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
1a950 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
1a960 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d 61 72  sable the two-ar
1a970 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73 69 6f  gument.** versio
1a980 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33 5f 74  n of the [fts3_t
1a990 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75 6e 63  okenizer()] func
1a9a0 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20 70 61  tion which is pa
1a9b0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 46 54  rt of the.** [FT
1a9c0 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20 73 65  S3] full-text se
1a9d0 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78 74 65  arch engine exte
1a9e0 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  nsion..** There 
1a9f0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
1aa00 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
1aa10 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
1aa20 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
1aa30 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
1aa40 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 66 74   0 to disable ft
1aa50 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 20 6f  s3_tokenizer() o
1aa60 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  r.** positive to
1aa70 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b   enable fts3_tok
1aa80 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65 67 61  enizer() or nega
1aa90 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68  tive to leave th
1aaa0 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75 6e 63  e setting.** unc
1aab0 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
1aac0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1aad0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
1aae0 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
1aaf0 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
1ab00 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
1ab10 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 66  dicate whether f
1ab20 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20 69 73  ts3_tokenizer is
1ab30 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
1ab40 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
1ab50 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
1ab60 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1ab70 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
1ab80 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
1ab90 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
1aba0 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  ew setting is no
1abb0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
1abc0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
1abd0 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
1abe0 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54  _ENABLE_LOAD_EXT
1abf0 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  ENSION</dt>.** <
1ac00 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
1ac10 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
1ac20 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
1ac30 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  e [sqlite3_load_
1ac40 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20  extension()].** 
1ac50 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65 70 65  interface indepe
1ac60 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65 20 5b  ndently of the [
1ac70 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
1ac80 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a  ] SQL function..
1ac90 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
1aca0 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65  enable_load_exte
1acb0 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65 6e 61  nsion()] API ena
1acc0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
1acd0 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43 2d 41   both the.** C-A
1ace0 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  PI [sqlite3_load
1acf0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 61 6e  _extension()] an
1ad00 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  d the SQL functi
1ad10 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69  on [load_extensi
1ad20 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  on()]..** There 
1ad30 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
1ad40 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
1ad50 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  ts..** When the 
1ad60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1ad70 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  o this interface
1ad80 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e 6c 79   is 1, then only
1ad90 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a 2a 2a   the C-API is.**
1ada0 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65   enabled and the
1adb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
1adc0 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64 2e 20  mains disabled. 
1add0 20 49 66 20 74 68 65 20 66 69 72 73 74 20 61 72   If the first ar
1ade0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 69  gument to.** thi
1adf0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 30  s interface is 0
1ae00 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68 65 20  , then both the 
1ae10 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20 53 51  C-API and the SQ
1ae20 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 64  L function are d
1ae30 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66 20 74  isabled..** If t
1ae40 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1ae50 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 6e 6f  t is -1, then no
1ae60 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d 61 64   changes are mad
1ae70 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20 65 69  e to state of ei
1ae80 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d 41 50  ther the.** C-AP
1ae90 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66 75 6e  I or the SQL fun
1aea0 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 73 65  ction..** The se
1aeb0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
1aec0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1aed0 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
1aee0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
1aef0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
1af00 69 63 61 74 65 20 77 68 65 74 68 65 72 20 5b 73  icate whether [s
1af10 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
1af20 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66 61  nsion()] interfa
1af30 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62 6c 65  ce.** is disable
1af40 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66 6f 6c  d or enabled fol
1af50 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
1af60 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
1af70 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a 20 62  rameter may.** b
1af80 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
1af90 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
1afa0 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e 67 20  the new setting 
1afb0 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
1afc0 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  back..** </dd>.*
1afd0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
1afe0 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44 42 4e  DBCONFIG_MAINDBN
1aff0 41 4d 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  AME</dt>.** <dd>
1b000 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
1b010 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
1b020 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
1b030 22 6d 61 69 6e 22 20 64 61 74 61 62 61 73 65 0a  "main" database.
1b040 2a 2a 20 73 63 68 65 6d 61 2e 20 20 5e 54 68 65  ** schema.  ^The
1b050 20 73 6f 6c 65 20 61 72 67 75 6d 65 6e 74 20 69   sole argument i
1b060 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1b070 20 63 6f 6e 73 74 61 6e 74 20 55 54 46 38 20 73   constant UTF8 s
1b080 74 72 69 6e 67 0a 2a 2a 20 77 68 69 63 68 20 77  tring.** which w
1b090 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 6e  ill become the n
1b0a0 65 77 20 73 63 68 65 6d 61 20 6e 61 6d 65 20 69  ew schema name i
1b0b0 6e 20 70 6c 61 63 65 20 6f 66 20 22 6d 61 69 6e  n place of "main
1b0c0 22 2e 20 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 64  ".  ^SQLite.** d
1b0d0 6f 65 73 20 6e 6f 74 20 6d 61 6b 65 20 61 20 63  oes not make a c
1b0e0 6f 70 79 20 6f 66 20 74 68 65 20 6e 65 77 20 6d  opy of the new m
1b0f0 61 69 6e 20 73 63 68 65 6d 61 20 6e 61 6d 65 20  ain schema name 
1b100 73 74 72 69 6e 67 2c 20 73 6f 20 74 68 65 20 61  string, so the a
1b110 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
1b120 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  st ensure that t
1b130 68 65 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73  he argument pass
1b140 65 64 20 69 6e 74 6f 20 74 68 69 73 20 44 42 43  ed into this DBC
1b150 4f 4e 46 49 47 20 6f 70 74 69 6f 6e 20 69 73 20  ONFIG option is 
1b160 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 75 6e 74  unchanged.** unt
1b170 69 6c 20 61 66 74 65 72 20 74 68 65 20 64 61 74  il after the dat
1b180 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b190 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64   closes..** </dd
1b1a0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1b1b0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43  TE_DBCONFIG_NO_C
1b1c0 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74  KPT_ON_CLOSE</dt
1b1d0 3e 0a 2a 2a 20 3c 64 64 3e 20 55 73 75 61 6c 6c  >.** <dd> Usuall
1b1e0 79 2c 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  y, when a databa
1b1f0 73 65 20 69 6e 20 77 61 6c 20 6d 6f 64 65 20 69  se in wal mode i
1b200 73 20 63 6c 6f 73 65 64 20 6f 72 20 64 65 74 61  s closed or deta
1b210 63 68 65 64 20 66 72 6f 6d 20 61 20 0a 2a 2a 20  ched from a .** 
1b220 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 2c  database handle,
1b230 20 53 51 4c 69 74 65 20 63 68 65 63 6b 73 20 69   SQLite checks i
1b240 66 20 74 68 69 73 20 77 69 6c 6c 20 6d 65 61 6e  f this will mean
1b250 20 74 68 61 74 20 74 68 65 72 65 20 61 72 65 20   that there are 
1b260 6e 6f 77 20 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65  now no .** conne
1b270 63 74 69 6f 6e 73 20 61 74 20 61 6c 6c 20 74 6f  ctions at all to
1b280 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 49   the database. I
1b290 66 20 73 6f 2c 20 69 74 20 70 65 72 66 6f 72 6d  f so, it perform
1b2a0 73 20 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 0a  s a checkpoint .
1b2b0 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 62 65 66  ** operation bef
1b2c0 6f 72 65 20 63 6c 6f 73 69 6e 67 20 74 68 65 20  ore closing the 
1b2d0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 54 68 69 73  connection. This
1b2e0 20 6f 70 74 69 6f 6e 20 6d 61 79 20 62 65 20 75   option may be u
1b2f0 73 65 64 20 74 6f 0a 2a 2a 20 6f 76 65 72 72 69  sed to.** overri
1b300 64 65 20 74 68 69 73 20 62 65 68 61 76 69 6f 75  de this behaviou
1b310 72 2e 20 54 68 65 20 66 69 72 73 74 20 70 61 72  r. The first par
1b320 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74 6f  ameter passed to
1b330 20 74 68 69 73 20 6f 70 65 72 61 74 69 6f 6e 0a   this operation.
1b340 2a 2a 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ** is an integer
1b350 20 2d 20 6e 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64   - non-zero to d
1b360 69 73 61 62 6c 65 20 63 68 65 63 6b 70 6f 69 6e  isable checkpoin
1b370 74 73 2d 6f 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20  ts-on-close, or 
1b380 7a 65 72 6f 20 28 74 68 65 0a 2a 2a 20 64 65 66  zero (the.** def
1b390 61 75 6c 74 29 20 74 6f 20 65 6e 61 62 6c 65 20  ault) to enable 
1b3a0 74 68 65 6d 2e 20 54 68 65 20 73 65 63 6f 6e 64  them. The second
1b3b0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
1b3c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
1b3d0 74 65 67 65 72 0a 2a 2a 20 69 6e 74 6f 20 77 68  teger.** into wh
1b3e0 69 63 68 20 69 73 20 77 72 69 74 74 65 6e 20 30  ich is written 0
1b3f0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
1b400 65 20 77 68 65 74 68 65 72 20 63 68 65 63 6b 70  e whether checkp
1b410 6f 69 6e 74 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a  oints-on-close.*
1b420 2a 20 68 61 76 65 20 62 65 65 6e 20 64 69 73 61  * have been disa
1b430 62 6c 65 64 20 2d 20 30 20 69 66 20 74 68 65 79  bled - 0 if they
1b440 20 61 72 65 20 6e 6f 74 20 64 69 73 61 62 6c 65   are not disable
1b450 64 2c 20 31 20 69 66 20 74 68 65 79 20 61 72 65  d, 1 if they are
1b460 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
1b470 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
1b480 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1b490 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20 20 20  G_MAINDBNAME    
1b4a0 20 20 20 20 20 20 20 20 31 30 30 30 20 2f 2a 20          1000 /* 
1b4b0 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f 0a 23  const char* */.#
1b4c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1b4d0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
1b4e0 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30 30               100
1b4f0 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69  1 /* void* int i
1b500 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
1b510 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
1b520 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20 20  ABLE_FKEY       
1b530 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74 20      1002 /* int 
1b540 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
1b550 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1b560 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20  ENABLE_TRIGGER  
1b570 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69 6e        1003 /* in
1b580 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1b590 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1b5a0 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f  G_ENABLE_FTS3_TO
1b5b0 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a 20  KENIZER 1004 /* 
1b5c0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1b5d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1b5e0 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f  FIG_ENABLE_LOAD_
1b5f0 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20 2f  EXTENSION 1005 /
1b600 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1b610 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1b620 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e  ONFIG_NO_CKPT_ON
1b630 5f 43 4c 4f 53 45 20 20 20 20 20 20 31 30 30 36  _CLOSE      1006
1b640 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1b650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b660 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
1b670 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
1b680 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54  ult Codes.** MET
1b690 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1b6a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b6b0 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
1b6c0 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
1b6d0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
1b6e0 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
1b6f0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
1b700 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
1b710 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
1b720 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
1b730 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
1b740 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
1b750 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
1b760 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c  tibility..*/.SQL
1b770 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1b780 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
1b790 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
1b7a0 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
1b7b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b7c0 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
1b7d0 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  id.** METHOD: sq
1b7e0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  lite3.**.** ^Eac
1b7f0 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20  h entry in most 
1b800 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65  SQLite tables (e
1b810 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f  xcept for [WITHO
1b820 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
1b830 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75  ).** has a uniqu
1b840 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
1b850 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
1b860 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
1b870 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
1b880 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
1b890 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
1b8a0 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
1b8b0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
1b8c0 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
1b8d0 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
1b8e0 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
1b8f0 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
1b900 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
1b910 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
1b920 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
1b930 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
1b940 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
1b950 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
1b960 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
1b970 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
1b980 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
1b990 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1b9a0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1b9b0 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63  owid(D) interfac
1b9c0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
1b9d0 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a  owid] of the .**
1b9e0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
1b9f0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
1ba00 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61   into a rowid ta
1ba10 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ble or [virtual 
1ba20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74  table].** on dat
1ba30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1ba40 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20   D..** ^Inserts 
1ba50 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f  into [WITHOUT RO
1ba60 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20  WID] tables are 
1ba70 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a  not recorded..**
1ba80 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
1ba90 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74  ul [INSERT]s int
1baa0 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a  o rowid tables.*
1bab0 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
1bac0 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61  rred on the data
1bad0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1bae0 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  D, .** then sqli
1baf0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1bb00 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
1bb10 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49   zero..**.** ^(I
1bb20 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
1bb30 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
1bb40 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
1bb50 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
1bb60 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
1bb70 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
1bb80 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
1bb90 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
1bba0 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
1bbb0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
1bbc0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
1bbd0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
1bbe0 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
1bbf0 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
1bc00 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
1bc10 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
1bc20 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1bc30 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
1bc40 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
1bc50 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
1bc60 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
1bc70 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
1bc80 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
1bc90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
1bca0 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
1bcb0 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
1bcc0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
1bcd0 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
1bce0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
1bcf0 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
1bd00 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
1bd10 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
1bd20 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
1bd30 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
1bd40 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
1bd50 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
1bd60 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
1bd70 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
1bd80 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
1bd90 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
1bda0 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
1bdb0 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
1bdc0 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
1bdd0 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
1bde0 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
1bdf0 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
1be00 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
1be10 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
1be20 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
1be30 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
1be40 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
1be50 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
1be60 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
1be70 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
1be80 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
1be90 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
1bea0 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
1beb0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1bec0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
1bed0 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
1bee0 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
1bef0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
1bf00 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
1bf10 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
1bf20 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
1bf30 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
1bf40 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
1bf50 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
1bf60 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
1bf70 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
1bf80 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
1bf90 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
1bfa0 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
1bfb0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
1bfc0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1bfd0 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
1bfe0 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
1bff0 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
1c000 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
1c010 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
1c020 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1c030 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
1c040 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
1c050 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
1c060 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
1c070 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
1c080 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1c090 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
1c0a0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1c0b0 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
1c0c0 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
1c0d0 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
1c0e0 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
1c0f0 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
1c100 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
1c110 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1c120 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1c130 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1c140 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
1c150 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1c160 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
1c170 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
1c180 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1c190 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1c1a0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1c1b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
1c1c0 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e  ows modified, in
1c1d0 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  serted or.** del
1c1e0 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
1c1f0 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
1c200 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
1c210 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  TE or DELETE.** 
1c220 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65  statement on the
1c230 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c240 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62  tion specified b
1c250 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  y the only param
1c260 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74  eter..** ^Execut
1c270 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
1c280 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
1c290 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64  ent does not mod
1c2a0 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  ify the value.**
1c2b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
1c2c0 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
1c2d0 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  * ^Only changes 
1c2e0 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79  made directly by
1c2f0 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44   the INSERT, UPD
1c300 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1c310 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63  atement are.** c
1c320 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69  onsidered - auxi
1c330 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
1c340 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20  used by [CREATE 
1c350 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
1c360 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67  rs], .** [foreig
1c370 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f  n key actions] o
1c380 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  r [REPLACE] cons
1c390 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
1c3a0 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  n are not counte
1c3b0 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65  d..** .** Change
1c3c0 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
1c3d0 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
1c3e0 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44   by .** [INSTEAD
1c3f0 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e   OF trigger | IN
1c400 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1c410 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
1c420 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a  ed. ^The value .
1c430 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
1c440 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1c450 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
1c460 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  er an INSERT, UP
1c470 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45  DATE or .** DELE
1c480 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e  TE statement run
1c490 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c   on a view is al
1c4a0 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20  ways zero. Only 
1c4b0 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20  changes made to 
1c4c0 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20  real .** tables 
1c4d0 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
1c4e0 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f  ** Things are mo
1c4f0 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69  re complicated i
1c500 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  f the sqlite3_ch
1c510 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
1c520 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   is.** executed 
1c530 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20  while a trigger 
1c540 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69  program is runni
1c550 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70  ng. This may hap
1c560 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72  pen if the.** pr
1c570 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b  ogram uses the [
1c580 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1c590 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73  nction], or if s
1c5a0 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61  ome other callba
1c5b0 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ck.** function i
1c5c0 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63  nvokes sqlite3_c
1c5d0 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c  hanges() directl
1c5e0 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a  y. Essentially:.
1c5f0 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  ** .** <ul>.**  
1c600 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65   <li> ^(Before e
1c610 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65  ntering a trigge
1c620 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61  r program the va
1c630 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a  lue returned by.
1c640 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65  **        sqlite
1c650 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
1c660 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41  tion is saved. A
1c670 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72  fter the trigger
1c680 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20   program .**    
1c690 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64      has finished
1c6a0 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76  , the original v
1c6b0 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64  alue is restored
1c6c0 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69  .)^.** .**   <li
1c6d0 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69  > ^(Within a tri
1c6e0 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63  gger program eac
1c6f0 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  h INSERT, UPDATE
1c700 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20   and DELETE .** 
1c710 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
1c720 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20   sets the value 
1c730 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1c740 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
1c750 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f  *        upon co
1c760 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d  mpletion as norm
1c770 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74  al. Of course, t
1c780 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e  his value will n
1c790 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20  ot include .**  
1c7a0 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65        any change
1c7b0 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73  s performed by s
1c7c0 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20  ub-triggers, as 
1c7d0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
1c7e0 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
1c7f0 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73   value will be s
1c800 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65  aved and restore
1c810 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62  d after each sub
1c820 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e  -trigger has run
1c830 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  .)^.** </ul>.** 
1c840 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20  .** ^This means 
1c850 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e  that if the chan
1c860 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1c870 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20  on (or similar) 
1c880 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  is used.** by th
1c890 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20  e first INSERT, 
1c8a0 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1c8b0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1c8c0 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20  n a trigger, it 
1c8d0 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
1c8e0 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65  value as set whe
1c8f0 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74  n the calling st
1c900 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78  atement began ex
1c910 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20  ecuting..** ^If 
1c920 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68  it is used by th
1c930 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73  e second or subs
1c940 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74  equent such stat
1c950 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74  ement within a t
1c960 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72  rigger .** progr
1c970 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  am, the value re
1c980 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20  turned reflects 
1c990 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1c9a0 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74  ws modified by t
1c9b0 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  he .** previous 
1c9c0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1c9d0 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
1c9e0 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
1c9f0 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a  me trigger..**.*
1ca00 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
1ca10 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1ca20 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1ca30 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
1ca40 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
1ca50 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e  ], and the [chan
1ca60 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1ca70 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
1ca80 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1ca90 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
1caa0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
1cab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1cac0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1cad0 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
1cae0 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
1caf0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1cb00 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
1cb10 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
1cb20 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  gful..*/.SQLITE_
1cb30 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1cb40 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
1cb50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cb60 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
1cb70 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
1cb80 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
1cb90 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1cba0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1cbb0 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  s the total numb
1cbc0 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72  er of rows inser
1cbd0 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72  ted, modified or
1cbe0 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61  .** deleted by a
1cbf0 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  ll [INSERT], [UP
1cc00 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
1cc10 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d  ] statements com
1cc20 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20  pleted.** since 
1cc30 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1cc40 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e  nection was open
1cc50 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  ed, including th
1cc60 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a  ose executed as.
1cc70 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67  ** part of trigg
1cc80 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78  er programs. ^Ex
1cc90 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
1cca0 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
1ccb0 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20  atement.** does 
1ccc0 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76  not affect the v
1ccd0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1cce0 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1ccf0 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a  hanges()..** .**
1cd00 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61   ^Changes made a
1cd10 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69  s part of [forei
1cd20 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
1cd30 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  are included in 
1cd40 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75  the.** count, bu
1cd50 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20  t those made as 
1cd60 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20  part of REPLACE 
1cd70 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
1cd80 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74  ution are.** not
1cd90 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  . ^Changes to a 
1cda0 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
1cdb0 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53  tercepted by INS
1cdc0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73  TEAD OF triggers
1cdd0 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75   .** are not cou
1cde0 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65  nted..** .** See
1cdf0 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
1ce00 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
1ce10 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
1ce20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
1ce30 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
1ce40 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
1ce50 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
1ce60 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1ce70 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
1ce80 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
1ce90 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
1cea0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
1ceb0 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1cec0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
1ced0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
1cee0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
1cef0 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
1cf00 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
1cf10 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ngful..*/.SQLITE
1cf20 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1cf30 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
1cf40 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1cf50 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
1cf60 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
1cf70 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
1cf80 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1cf90 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1cfa0 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
1cfb0 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
1cfc0 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
1cfd0 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
1cfe0 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
1cff0 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
1d000 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
1d010 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
1d020 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
1d030 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
1d040 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
1d050 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
1d060 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
1d070 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
1d080 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
1d090 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
1d0a0 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
1d0b0 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
1d0c0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
1d0d0 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
1d0e0 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
1d0f0 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
1d100 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
1d110 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
1d120 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
1d130 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
1d140 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1d150 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
1d160 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1d170 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
1d180 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
1d190 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
1d1a0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1d1b0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1d1c0 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
1d1d0 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
1d1e0 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
1d1f0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
1d200 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1d210 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
1d220 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
1d230 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
1d240 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
1d250 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
1d260 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
1d270 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
1d280 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
1d290 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
1d2a0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
1d2b0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
1d2c0 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
1d2d0 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
1d2e0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1d2f0 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1d300 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
1d310 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
1d320 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
1d330 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
1d340 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
1d350 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
1d360 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
1d370 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
1d380 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
1d390 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
1d3a0 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
1d3b0 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
1d3c0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1d3d0 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
1d3e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d3f0 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
1d400 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
1d410 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1d420 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1d430 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1d440 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1d450 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
1d460 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
1d470 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
1d480 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
1d490 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
1d4a0 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
1d4b0 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
1d4c0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1d4d0 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
1d4e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1d4f0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1d500 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
1d510 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
1d520 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
1d530 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
1d540 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
1d550 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
1d560 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
1d570 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1d580 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
1d590 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
1d5a0 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
1d5b0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
1d5c0 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
1d5d0 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
1d5e0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1d5f0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1d600 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1d610 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1d620 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
1d630 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1d640 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
1d650 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
1d660 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
1d670 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
1d680 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
1d690 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
1d6a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1d6b0 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
1d6c0 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
1d6d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d6e0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
1d6f0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1d700 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
1d710 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1d720 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
1d730 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
1d740 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
1d750 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
1d760 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
1d770 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
1d780 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
1d790 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
1d7a0 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
1d7b0 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
1d7c0 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
1d7d0 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
1d7e0 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
1d7f0 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
1d800 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
1d810 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1d820 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
1d830 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
1d840 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
1d850 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
1d860 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
1d870 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
1d880 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
1d890 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
1d8a0 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
1d8b0 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
1d8c0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
1d8d0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
1d8e0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
1d8f0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
1d900 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
1d910 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
1d920 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
1d930 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
1d940 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
1d950 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
1d960 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
1d970 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
1d980 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
1d990 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
1d9a0 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
1d9b0 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
1d9c0 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
1d9d0 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
1d9e0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
1d9f0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
1da00 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
1da10 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1da20 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
1da30 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1da40 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
1da50 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
1da60 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
1da70 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
1da80 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
1da90 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1daa0 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
1dab0 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
1dac0 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
1dad0 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
1dae0 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
1daf0 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
1db00 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
1db10 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
1db20 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
1db30 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1db40 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
1db50 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
1db60 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
1db70 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
1db80 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
1db90 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
1dba0 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
1dbb0 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
1dbc0 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
1dbd0 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
1dbe0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1dbf0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
1dc00 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
1dc10 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
1dc20 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
1dc30 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1dc40 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
1dc50 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
1dc60 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1dc70 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1dc80 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1dc90 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1dca0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
1dcb0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1dcc0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1dcd0 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
1dce0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1dcf0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1dd00 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
1dd10 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c  te order..*/.SQL
1dd20 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1dd30 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
1dd40 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53  st char *sql);.S
1dd50 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1dd60 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1dd70 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
1dd80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1dd90 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
1dda0 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
1ddb0 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
1ddc0 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  rors.** KEYWORDS
1ddd0 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20  : {busy-handler 
1dde0 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20  callback} {busy 
1ddf0 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48  handler}.** METH
1de00 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1de10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
1de20 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c  usy_handler(D,X,
1de30 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  P) routine sets 
1de40 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
1de50 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69  ion X.** that mi
1de60 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
1de70 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
1de80 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
1de90 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
1dea0 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61   access a databa
1deb0 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61  se table associa
1dec0 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74  ted with.** [dat
1ded0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1dee0 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72  ] D when another
1def0 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
1df00 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61  ocess has the ta
1df10 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54  ble locked..** T
1df20 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
1df30 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66  handler() interf
1df40 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69  ace is used to i
1df50 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c  mplement.** [sql
1df60 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1df70 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41  t()] and [PRAGMA
1df80 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a   busy_timeout]..
1df90 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
1dfa0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1dfb0 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
1dfc0 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65  E_BUSY].** is re
1dfd0 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
1dfe0 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
1dff0 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
1e000 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1e010 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
1e020 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
1e030 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
1e040 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
1e050 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
1e060 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
1e070 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
1e080 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
1e090 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
1e0a0 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
1e0b0 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
1e0c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1e0d0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1e0e0 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
1e0f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1e100 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1e110 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1e120 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
1e130 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
1e140 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
1e150 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69  en invoked previ
1e160 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61  ously for the sa
1e170 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
1e180 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
1e190 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
1e1a0 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
1e1b0 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
1e1c0 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
1e1d0 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
1e1e0 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
1e1f0 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72  E_BUSY] is retur
1e200 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  ned.** to the ap
1e210 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  plication..** ^I
1e220 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
1e230 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1e240 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
1e250 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
1e260 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
1e270 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20  atabase and the 
1e280 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
1e290 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
1e2a0 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
1e2b0 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
1e2c0 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
1e2d0 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
1e2e0 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
1e2f0 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
1e300 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
1e310 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
1e320 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
1e330 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
1e340 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
1e350 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
1e360 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
1e370 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1e380 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1e390 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20  tion instead of 
1e3a0 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a  invoking the .**
1e3b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1e3c0 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
1e3d0 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
1e3e0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1e3f0 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
1e400 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
1e410 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
1e420 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
1e430 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
1e440 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
1e450 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
1e460 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
1e470 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
1e480 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
1e490 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
1e4a0 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
1e4b0 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
1e4c0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1e4d0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
1e4e0 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
1e4f0 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
1e500 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
1e510 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1e520 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
1e530 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
1e540 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
1e550 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
1e560 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
1e570 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
1e580 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
1e590 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
1e5a0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
1e5b0 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1e5c0 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
1e5d0 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
1e5e0 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
1e5f0 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
1e600 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
1e610 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
1e620 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
1e630 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
1e640 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
1e650 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1e660 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ULL..**.** ^(The
1e670 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1e680 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1e690 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
1e6a0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
1e6b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1e6c0 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
1e6d0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
1e6e0 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
1e6f0 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
1e700 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
1e710 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1e720 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1e730 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  .** or evaluatin
1e740 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  g [PRAGMA busy_t
1e750 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63  imeout=N] will c
1e760 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73  hange the.** bus
1e770 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68  y handler and th
1e780 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65  us clear any pre
1e790 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79  viously set busy
1e7a0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
1e7b0 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
1e7c0 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
1e7d0 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
1e7e0 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
1e7f0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1e800 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1e810 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1e820 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ler.  In other w
1e830 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73  ords,.** the bus
1e840 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74  y handler is not
1e850 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79   reentrant.  Any
1e860 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
1e870 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
1e880 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
1e890 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
1e8a0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
1e8b0 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
1e8c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1e8d0 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
1e8e0 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
1e8f0 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1e900 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  dler..*/.SQLITE_
1e910 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1e920 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
1e930 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69  ite3*,int(*)(voi
1e940 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a  d*,int),void*);.
1e950 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e960 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
1e970 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  out.** METHOD: s
1e980 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1e990 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
1e9a0 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
1e9b0 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
1e9c0 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
1e9d0 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
1e9e0 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
1e9f0 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
1ea00 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
1ea10 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
1ea20 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
1ea30 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
1ea40 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1ea50 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1ea60 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
1ea70 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
1ea80 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
1ea90 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1eaa0 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
1eab0 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
1eac0 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
1ead0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1eae0 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
1eaf0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
1eb00 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
1eb10 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
1eb20 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
1eb30 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
1eb40 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
1eb50 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
1eb60 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lers..**.** ^(Th
1eb70 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1eb80 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1eb90 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
1eba0 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1ebb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1ebc0 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  at any given mom
1ebd0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
1ebe0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
1ebf0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
1ec00 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
1ec10 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
1ec20 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
1ec30 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
1ec40 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
1ec50 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
1ec60 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  red.)^.**.** See
1ec70 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20   also:  [PRAGMA 
1ec80 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f  busy_timeout].*/
1ec90 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1eca0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1ecb0 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
1ecc0 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
1ecd0 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
1ece0 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
1ecf0 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
1ed00 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
1ed10 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ite3.**.** This 
1ed20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
1ed30 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
1ed40 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
1ed50 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1ed60 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
1ed70 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
1ed80 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
1ed90 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
1eda0 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
1edb0 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
1edc0 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
1edd0 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
1ede0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
1edf0 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
1ee00 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
1ee10 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
1ee20 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
1ee30 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
1ee40 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
1ee50 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
1ee60 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
1ee70 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
1ee80 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
1ee90 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
1eea0 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
1eeb0 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
1eec0 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
1eed0 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
1eee0 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
1eef0 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
1ef00 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
1ef10 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
1ef20 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
1ef30 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
1ef40 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1ef50 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
1ef60 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
1ef70 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1ef80 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
1ef90 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
1efa0 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
1efb0 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
1efc0 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
1efd0 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
1efe0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1eff0 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
1f000 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
1f010 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
1f020 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
1f030 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
1f040 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
1f050 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
1f060 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
1f070 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
1f080 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
1f090 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
1f0a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1f0b0 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
1f0c0 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
1f0d0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1f0e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
1f0f0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1f100 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
1f110 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
1f120 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
1f130 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
1f140 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
1f150 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
1f160 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
1f170 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
1f180 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
1f190 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
1f1a0 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
1f1b0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1f1c0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
1f1d0 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
1f1e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
1f1f0 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
1f200 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
1f210 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1f220 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1f230 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1f240 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
1f250 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
1f260 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1f270 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
1f280 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
1f290 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
1f2a0 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
1f2b0 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
1f2c0 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
1f2d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1f2e0 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
1f2f0 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
1f300 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
1f310 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
1f320 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
1f330 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
1f340 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
1f350 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
1f360 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
1f370 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
1f380 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
1f390 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
1f3a0 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
1f3b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1f3c0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1f3d0 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
1f3e0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1f3f0 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
1f400 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1f410 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
1f420 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
1f430 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
1f440 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
1f450 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1f460 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
1f470 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1f480 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
1f490 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1f4a0 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
1f4b0 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
1f4c0 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
1f4d0 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
1f4e0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
1f4f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1f500 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
1f510 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
1f520 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1f530 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
1f540 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1f550 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
1f560 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
1f570 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
1f580 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
1f590 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
1f5a0 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
1f5b0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
1f5c0 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
1f5d0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
1f5e0 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
1f5f0 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
1f600 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
1f610 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
1f620 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
1f630 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
1f640 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
1f650 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
1f660 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
1f670 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
1f680 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
1f690 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
1f6a0 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
1f6b0 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
1f6c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
1f6d0 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
1f6e0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1f6f0 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
1f700 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
1f710 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
1f720 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1f730 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
1f740 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1f750 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
1f760 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
1f770 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
1f780 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
1f790 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1f7a0 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
1f7b0 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
1f7c0 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
1f7d0 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
1f7e0 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
1f7f0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1f800 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
1f810 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
1f820 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
1f830 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
1f840 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
1f850 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
1f860 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
1f870 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
1f880 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
1f890 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
1f8a0 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
1f8b0 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
1f8c0 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
1f8d0 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
1f8e0 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
1f8f0 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
1f900 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
1f910 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
1f920 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1f930 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1f940 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51  errmsg()]..*/.SQ
1f950 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1f960 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1f970 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1f980 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1f990 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1f9a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1f9b0 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1f9c0 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1f9d0 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1f9e0 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1f9f0 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1fa00 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1fa10 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1fa20 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1fa30 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1fa40 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1fa50 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1fa60 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1fa70 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1fa80 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1fa90 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1faa0 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1fab0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1fac0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1fad0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1fae0 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1faf0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1fb00 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1fb10 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1fb20 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1fb30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1fb40 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1fb50 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1fb60 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1fb70 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1fb80 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1fb90 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ry..** These rou
1fba0 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64  tines understand
1fbb0 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d   most of the com
1fbc0 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69  mon K&R formatti
1fbd0 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70  ng options,.** p
1fbe0 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  lus some additio
1fbf0 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64  nal non-standard
1fc00 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c   formats, detail
1fc10 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74  ed below..** Not
1fc20 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74  e that some of t
1fc30 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20  he more obscure 
1fc40 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1fc50 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a  ns from recent.*
1fc60 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e  * C-library stan
1fc70 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65  dards are omitte
1fc80 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c  d from this impl
1fc90 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ementation..**.*
1fca0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1fcb0 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
1fcc0 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
1fcd0 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
1fce0 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
1fcf0 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
1fd00 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
1fd10 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
1fd20 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1fd30 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
1fd40 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
1fd50 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
1fd60 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
1fd70 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
1fd80 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
1fd90 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
1fda0 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
1fdb0 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
1fdc0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
1fdd0 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
1fde0 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
1fdf0 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
1fe00 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
1fe10 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1fe20 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
1fe30 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
1fe40 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
1fe50 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
1fe60 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
1fe70 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
1fe80 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
1fe90 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1fea0 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
1feb0 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
1fec0 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
1fed0 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
1fee0 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
1fef0 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
1ff00 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
1ff10 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
1ff20 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
1ff30 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
1ff40 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
1ff50 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
1ff60 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1ff70 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
1ff80 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
1ff90 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
1ffa0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1ffb0 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
1ffc0 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
1ffd0 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
1ffe0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
1fff0 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
20000 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
20010 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
20020 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
20030 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
20040 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
20050 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
20060 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
20070 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
20080 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
20090 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
200a0 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
200b0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
200c0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
200d0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
200e0 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
200f0 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
20100 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
20110 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
20120 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
20130 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
20140 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
20150 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
20160 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
20170 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
20180 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
20190 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
201a0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
201b0 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
201c0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
201d0 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
201e0 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
201f0 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
20200 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
20210 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
20220 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
20230 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
20240 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
20250 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
20260 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
20270 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
20280 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
20290 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
202a0 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
202b0 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
202c0 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
202d0 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
202e0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
202f0 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
20300 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
20310 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
20320 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
20330 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
20340 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77   "%q", "%Q", "%w
20350 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  " and "%z" optio
20360 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
20370 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
20380 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
20390 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
203a0 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
203b0 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
203c0 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
203d0 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
203e0 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
203f0 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
20400 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
20410 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
20420 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
20430 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
20440 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
20450 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
20460 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
20470 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
20480 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
20490 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
204a0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
204b0 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
204c0 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
204d0 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
204e0 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
204f0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
20500 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
20510 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
20520 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
20530 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
20540 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
20550 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
20560 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
20570 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
20580 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
20590 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
205a0 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
205b0 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
205c0 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
205d0 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
205e0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
205f0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
20600 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
20610 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
20620 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
20630 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
20640 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
20650 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
20660 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
20670 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
20680 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
20690 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
206a0 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
206b0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
206c0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
206d0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
206e0 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
206f0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
20700 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
20710 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
20720 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
20730 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
20740 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
20750 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
20760 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
20770 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
20780 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
20790 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
207a0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
207b0 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
207c0 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
207d0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
207e0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
207f0 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
20800 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
20810 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
20820 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
20830 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
20840 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
20850 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
20860 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
20870 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
20880 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
20890 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
208a0 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
208b0 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
208c0 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
208d0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
208e0 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
208f0 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
20900 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
20910 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
20920 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
20930 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
20940 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
20950 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
20960 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
20970 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
20980 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
20990 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
209a0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
209b0 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
209c0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
209d0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
209e0 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
209f0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
20a00 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
20a10 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
20a20 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
20a30 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
20a40 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
20a50 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
20a60 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
20a70 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
20a80 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
20a90 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
20aa0 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
20ab0 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
20ac0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
20ad0 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74  (The "%w" format
20ae0 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c  ting option is l
20af0 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20  ike "%q" except 
20b00 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20  that it expects 
20b10 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e  to.** be contain
20b20 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65  ed within double
20b30 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20  -quotes instead 
20b40 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  of single quotes
20b50 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61  , and it.** esca
20b60 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71  pes the double-q
20b70 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69  uote character i
20b80 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69  nstead of the si
20b90 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68  ngle-quote.** ch
20ba0 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20  aracter.)^  The 
20bb0 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%w" formatting 
20bc0 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64  option is intend
20bd0 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e  ed for safely in
20be0 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65  serting.** table
20bf0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   and column name
20c00 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75  s into a constru
20c10 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  cted SQL stateme
20c20 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  nt..**.** ^(The 
20c30 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
20c40 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
20c50 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20  e "%s" but with 
20c60 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
20c70 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
20c80 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
20c90 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
20ca0 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
20cb0 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
20cc0 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
20cd0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
20ce0 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  g.)^.*/.SQLITE_A
20cf0 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
20d00 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
20d10 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54  har*,...);.SQLIT
20d20 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
20d30 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
20d40 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
20d50 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
20d60 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
20d70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
20d80 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
20d90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
20da0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
20db0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
20dc0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
20dd0 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
20de0 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
20df0 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
20e00 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
20e10 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
20e20 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
20e30 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
20e40 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
20e50 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
20e60 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
20e70 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
20e80 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
20e90 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
20ea0 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
20eb0 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
20ec0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
20ed0 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
20ee0 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
20ef0 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
20f00 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
20f10 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
20f20 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
20f30 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
20f40 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
20f50 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
20f60 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
20f70 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
20f80 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
20f90 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
20fa0 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
20fb0 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
20fc0 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
20fd0 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
20fe0 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
20ff0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
21000 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
21010 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
21020 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
21030 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
21040 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
21050 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
21060 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
21070 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
21080 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75  _malloc64(N) rou
21090 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20  tine works just 
210a0 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  like.** sqlite3_
210b0 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74  malloc(N) except
210c0 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e   that N is an un
210d0 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e  signed 64-bit in
210e0 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
210f0 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d   of a signed 32-
21100 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  bit integer..**.
21110 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
21120 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
21130 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
21140 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
21150 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
21160 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
21170 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
21180 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
21190 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
211a0 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
211b0 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
211c0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
211d0 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
211e0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
211f0 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
21200 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
21210 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
21220 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
21230 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
21240 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
21250 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
21260 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
21270 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
21280 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
21290 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
212a0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
212b0 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
212c0 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
212d0 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
212e0 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
212f0 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
21300 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
21310 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
21320 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
21330 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
21340 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
21350 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
21360 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
21370 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
21380 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
21390 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
213a0 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  loc()..**.** ^Th
213b0 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
213c0 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  c(X,N) interface
213d0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
213e0 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
213f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
21400 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73   X to be at leas
21410 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49  t N bytes..** ^I
21420 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  f the X paramete
21430 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
21440 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20  lloc(X,N).** is 
21450 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
21460 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
21470 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
21480 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
21490 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a  te3_malloc(N)..*
214a0 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61  * ^If the N para
214b0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
214c0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73  _realloc(X,N) is
214d0 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
214e0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
214f0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
21500 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
21510 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
21520 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71  _free(X)..** ^sq
21530 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
21540 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  N) returns a poi
21550 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
21560 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
21570 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
21580 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
21590 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
215a0 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61  nt memory is ava
215b0 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
215c0 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
215d0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
215e0 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
215f0 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
21600 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
21610 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
21620 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
21630 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
21640 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
21650 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
21660 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
21670 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
21680 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
21690 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
216a0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
216b0 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20   N is positive, 
216c0 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f  then the.** prio
216d0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
216e0 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
216f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
21700 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74  alloc64(X,N) int
21710 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68  erfaces works th
21720 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
21730 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
21740 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
21750 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69  is a 64-bit unsi
21760 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73  gned integer ins
21770 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d  tead.** of a 32-
21780 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
21790 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20  er..**.** ^If X 
217a0 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  is a memory allo
217b0 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c  cation previousl
217c0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
217d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
217e0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
217f0 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33  loc64(), sqlite3
21800 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73  _realloc(), or s
21810 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
21820 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  (), then.** sqli
21830 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
21840 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
21850 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c   that memory all
21860 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73  ocation in bytes
21870 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
21880 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
21890 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67  te3_msize(X) mig
218a0 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
218b0 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  n the number.** 
218c0 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74  of bytes request
218d0 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c  ed when X was al
218e0 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20  located.  ^If X 
218f0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
21900 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  r then.** sqlite
21910 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
21920 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70  ns zero.  If X p
21930 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69  oints to somethi
21940 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a  ng that is not.*
21950 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  * the beginning 
21960 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
21970 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70  tion, or if it p
21980 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65  oints to a forme
21990 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d  rly.** valid mem
219a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
219b0 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e  hat has now been
219c0 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65   freed, then the
219d0 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
219e0 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
219f0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
21a00 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66  d possibly harmf
21a10 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ul..**.** ^The m
21a20 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
21a30 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
21a40 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
21a50 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
21a60 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e  3_malloc64(), an
21a70 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
21a80 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  c64().** is alwa
21a90 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
21aa0 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
21ab0 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
21ac0 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
21ad0 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
21ae0 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
21af0 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
21b00 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
21b10 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
21b20 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
21b30 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
21b40 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
21b50 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
21b60 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
21b70 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
21b80 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
21b90 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
21ba0 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
21bb0 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
21bc0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
21bd0 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
21be0 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
21bf0 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
21c00 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
21c10 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
21c20 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
21c30 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
21c40 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
21c50 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
21c60 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
21c70 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
21c80 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
21c90 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
21ca0 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
21cb0 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
21cc0 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
21cd0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
21ce0 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
21cf0 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
21d00 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
21d10 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
21d20 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
21d30 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
21d40 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
21d50 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
21d60 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
21d70 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
21d80 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
21d90 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
21da0 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
21db0 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
21dc0 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
21dd0 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
21de0 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
21df0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
21e00 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
21e10 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
21e20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
21e30 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
21e40 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
21e50 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
21e60 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
21e70 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
21e80 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
21e90 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
21ea0 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
21eb0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
21ec0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
21ed0 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
21ee0 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
21ef0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
21f00 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
21f10 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
21f20 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
21f30 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
21f40 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
21f50 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
21f60 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
21f70 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  oc(int);.SQLITE_
21f80 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
21f90 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74  3_malloc64(sqlit
21fa0 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49  e3_uint64);.SQLI
21fb0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
21fc0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
21fd0 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
21fe0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
21ff0 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69  e3_realloc64(voi
22000 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  d*, sqlite3_uint
22010 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
22020 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
22030 65 28 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  e(void*);.SQLITE
22040 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 75 69 6e  _API sqlite3_uin
22050 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  t64 sqlite3_msiz
22060 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
22070 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
22080 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
22090 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
220a0 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
220b0 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
220c0 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
220d0 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
220e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
220f0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
22100 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
22110 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
22120 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
22130 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
22140 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
22150 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
22160 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
22170 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
22180 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
22190 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
221a0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
221b0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
221c0 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
221d0 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
221e0 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
221f0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
22200 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
22210 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
22220 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
22230 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
22240 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
22250 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
22260 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
22270 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
22280 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
22290 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
222a0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
222b0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
222c0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
222d0 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
222e0 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
222f0 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
22300 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
22310 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
22320 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
22330 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
22340 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
22350 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
22360 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
22370 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
22380 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
22390 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
223a0 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
223b0 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
223c0 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
223d0 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
223e0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
223f0 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
22400 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
22410 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
22420 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
22430 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
22440 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
22450 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
22460 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
22470 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
22480 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
22490 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
224a0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
224b0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
224c0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
224d0 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ed(void);.SQLITE
224e0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
224f0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
22500 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
22510 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
22520 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
22530 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
22540 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
22550 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
22560 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
22570 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
22580 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
22590 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
225a0 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
225b0 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
225c0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
225d0 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
225e0 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
225f0 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
22600 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
22610 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
22620 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
22630 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
22640 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
22650 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
22660 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
22670 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
22680 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
22690 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
226a0 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
226b0 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
226c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
226d0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
226e0 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
226f0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
22700 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20  to buffer P..** 
22710 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72  ^The P parameter
22720 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70   can be a NULL p
22730 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ointer..**.** ^I
22740 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  f this routine h
22750 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76  as not been prev
22760 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72  iously called or
22770 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
22780 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c  .** call had N l
22790 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20  ess than one or 
227a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
227b0 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50  or P, then the P
227c0 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64  RNG is.** seeded
227d0 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
227e0 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
227f0 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
22800 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65  method of.** the
22810 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
22820 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
22830 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f  * ^If the previo
22840 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
22850 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e  routine had an N
22860 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e   of 1 or more an
22870 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20  d a.** non-NULL 
22880 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64  P then the pseud
22890 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
228a0 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
228b0 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
228c0 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
228d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
228e0 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
228f0 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49   method..*/.SQLI
22900 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
22910 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
22920 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
22930 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22940 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
22950 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
22960 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
22970 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
22980 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
22990 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
229a0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
229b0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
229c0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
229d0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
229e0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
229f0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
22a00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
22a10 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
22a20 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
22a30 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
22a40 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
22a50 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
22a60 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
22a70 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22a80 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
22a90 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
22aa0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
22ab0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
22ac0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
22ad0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
22ae0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
22af0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
22b00 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
22b10 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
22b20 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
22b30 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
22b40 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
22b50 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
22b60 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
22b70 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
22b80 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22b90 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
22ba0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
22bb0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
22bc0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
22bd0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
22be0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
22bf0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
22c00 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
22c10 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
22c20 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
22c30 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
22c40 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
22c50 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
22c60 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
22c70 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
22c80 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
22c90 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
22ca0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
22cb0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
22cc0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
22cd0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
22ce0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
22cf0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
22d00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22d10 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
22d20 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
22d30 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
22d40 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
22d50 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
22d60 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
22d70 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
22d80 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
22d90 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
22da0 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
22db0 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
22dc0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
22dd0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
22de0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
22df0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
22e00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
22e10 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
22e20 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
22e30 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
22e40 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
22e50 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
22e60 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
22e70 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
22e80 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
22e90 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
22ea0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
22eb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
22ec0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
22ed0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
22ee0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
22ef0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
22f00 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
22f10 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
22f20 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
22f30 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
22f40 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
22f50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
22f60 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
22f70 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
22f80 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
22f90 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
22fa0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
22fb0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
22fc0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
22fd0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
22fe0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
22ff0 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
23000 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
23010 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
23020 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
23030 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
23040 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
23050 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
23060 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
23070 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
23080 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
23090 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
230a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
230b0 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
230c0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
230d0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
230e0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
230f0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
23100 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
23110 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
23120 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
23130 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
23140 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
23150 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
23160 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
23170 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
23180 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
23190 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
231a0 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
231b0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
231c0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
231d0 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
231e0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
231f0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
23200 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
23210 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
23220 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
23230 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
23240 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
23250 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
23260 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
23270 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
23280 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
23290 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
232a0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
232b0 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
232c0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
232d0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
232e0 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
232f0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
23300 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
23310 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
23320 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
23330 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
23340 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
23350 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
23360 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
23370 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
23380 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
23390 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
233a0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
233b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
233c0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
233d0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
233e0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
233f0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
23400 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
23410 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
23420 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
23430 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
23440 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
23450 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
23460 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
23470 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
23480 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
23490 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
234a0 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
234b0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
234c0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
234d0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
234e0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
234f0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
23500 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
23510 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
23520 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
23530 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
23540 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
23550 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
23560 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
23570 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
23580 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
23590 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
235a0 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
235b0 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
235c0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
235d0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
235e0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
235f0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
23600 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
23610 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
23620 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
23630 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
23640 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
23650 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
23660 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
23670 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
23680 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
23690 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
236a0 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
236b0 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
236c0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
236d0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
236e0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
236f0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
23700 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
23710 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
23720 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
23730 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
23740 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
23750 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
23760 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
23770 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
23780 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
23790 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
237a0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
237b0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
237c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
237d0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
237e0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
237f0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
23800 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
23810 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
23820 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
23830 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
23840 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
23850 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
23860 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
23870 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
23880 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
23890 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
238a0 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
238b0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
238c0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
238d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
238e0 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
238f0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
23900 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
23910 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
23920 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
23930 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
23940 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
23950 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
23960 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
23970 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
23980 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
23990 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
239a0 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
239b0 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
239c0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
239d0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
239e0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
239f0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
23a00 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
23a10 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
23a20 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
23a30 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
23a40 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
23a50 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
23a60 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
23a70 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
23a80 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53  ema change..*/.S
23a90 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
23aa0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
23ab0 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
23ac0 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
23ad0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
23ae0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
23af0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
23b00 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
23b10 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
23b20 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23b30 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
23b40 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
23b50 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
23b60 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
23b70 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
23b80 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
23b90 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
23ba0 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
23bb0 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
23bc0 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
23bd0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
23be0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
23bf0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
23c00 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
23c10 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
23c20 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
23c30 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
23c40 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
23c50 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
23c60 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
23c70 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
23c80 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
23c90 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
23ca0 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c   [conflict resol
23cb0 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72  ution mode].** r
23cc0 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65  eturned from the
23cd0 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
23ce0 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
23cf0 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
23d00 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
23d10 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
23d20 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
23d30 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
23d40 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23d50 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
23d60 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
23d70 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
23d80 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
23d90 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
23da0 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
23db0 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
23dc0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
23dd0 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
23de0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
23df0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
23e00 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
23e10 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
23e20 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
23e30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
23e40 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
23e50 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
23e60 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
23e70 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
23e80 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
23e90 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
23ea0 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
23eb0 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
23ec0 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
23ed0 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
23ee0 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
23ef0 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
23f00 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
23f10 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
23f20 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
23f30 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
23f40 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
23f50 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
23f60 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
23f70 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
23f80 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
23f90 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
23fa0 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
23fb0 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
23fc0 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
23fd0 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
23fe0 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
23ff0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
24000 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
24010 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
24020 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
24030 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
24040 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
24050 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
24060 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
24070 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
24080 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
24090 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
240a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
240b0 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
240c0 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
240d0 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
240e0 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
240f0 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
24100 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
24110 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
24120 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
24130 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
24140 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
24150 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
24160 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24170 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24180 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
24190 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
241a0 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
241b0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
241c0 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
241d0 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
241e0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
241f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24200 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
24210 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
24220 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
24230 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24240 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24250 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
24260 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
24270 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
24280 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
24290 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
242a0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
242b0 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
242c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
242d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
242e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
242f0 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
24300 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
24310 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
24320 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
24330 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24340 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
24350 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
24360 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
24370 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
24380 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24390 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
243a0 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
243b0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
243c0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
243d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
243e0 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
243f0 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
24400 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
24410 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
24420 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
24430 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
24440 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
24450 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
24460 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
24470 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
24480 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
24490 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
244a0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
244b0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
244c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
244d0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
244e0 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
244f0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
24500 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
24510 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
24520 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
24530 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
24540 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
24550 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
24560 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
24570 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
24580 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
24590 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
245a0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
245b0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
245c0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
245d0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
245e0 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
245f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
24600 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
24610 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
24620 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
24630 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
24640 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24650 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
24660 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
24670 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
24680 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
24690 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
246a0 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
246b0 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
246c0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
246d0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
246e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
246f0 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
24700 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
24710 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
24720 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24730 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24740 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
24750 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
24760 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
24770 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
24780 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24790 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
247a0 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
247b0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
247c0 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
247d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
247e0 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
247f0 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
24800 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
24810 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
24820 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24830 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
24840 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
24850 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
24860 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
24870 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24880 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
24890 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
248a0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
248b0 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
248c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
248d0 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
248e0 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
248f0 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
24900 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
24910 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
24920 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
24930 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
24940 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
24950 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
24960 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
24970 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
24980 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
24990 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
249a0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
249b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
249c0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
249d0 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
249e0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
249f0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
24a00 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
24a10 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
24a20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
24a30 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
24a40 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
24a50 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
24a60 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
24a70 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
24a80 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
24a90 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
24aa0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
24ab0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
24ac0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
24ad0 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
24ae0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
24af0 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
24b00 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
24b10 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
24b20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
24b30 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
24b40 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
24b50 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
24b60 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
24b70 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
24b80 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
24b90 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
24ba0 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
24bb0 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
24bc0 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
24bd0 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20  ITE_RECURSIVE   
24be0 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a           33   /*
24bf0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
24c00 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
24c10 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
24c20 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
24c30 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
24c40 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
24c50 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
24c60 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
24c70 20 64 65 70 72 65 63 61 74 65 64 2e 20 55 73 65   deprecated. Use
24c80 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72   the [sqlite3_tr
24c90 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  ace_v2()] interf
24ca0 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f  ace.** instead o
24cb0 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64  f the routines d
24cc0 65 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a  escribed here..*
24cd0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
24ce0 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
24cf0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
24d00 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
24d10 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
24d20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
24d30 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
24d40 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
24d50 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
24d60 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
24d70 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
24d80 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
24d90 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
24da0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
24db0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
24dc0 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
24dd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
24de0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24df0 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
24e00 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
24e10 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
24e20 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
24e30 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
24e40 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
24e50 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
24e60 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
24e70 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
24e80 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
24e90 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
24ea0 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
24eb0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
24ec0 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
24ed0 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
24ee0 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
24ef0 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
24f00 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
24f10 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
24f20 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er.)^.**.** The 
24f30 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
24f40 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
24f50 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61  e-time option ca
24f60 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d  n be used to lim
24f70 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68  it.** the length
24f80 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
24f90 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20  eter] expansion 
24fa0 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  in the output of
24fb0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
24fc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
24fd0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
24fe0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
24ff0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
25000 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
25010 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
25020 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
25030 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
25040 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
25050 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
25060 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
25070 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
25080 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
25090 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
250a0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
250b0 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
250c0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
250d0 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
250e0 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
250f0 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
25100 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
25110 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
25120 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
25130 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
25140 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
25150 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
25160 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
25170 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
25180 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
25190 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
251a0 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
251b0 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
251c0 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
251d0 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
251e0 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
251f0 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
25200 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
25210 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
25220 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
25230 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
25240 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
25250 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
25260 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
25270 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a  EPRECATED void *
25280 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
25290 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
252a0 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
252b0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
252c0 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  d*);.SQLITE_API 
252d0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
252e0 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  D void *sqlite3_
252f0 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
25300 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
25310 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
25320 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
25330 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
25340 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25350 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74   SQL Trace Event
25360 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
25370 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45  DS: SQLITE_TRACE
25380 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
25390 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20  stants identify 
253a0 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74  classes of event
253b0 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f  s that can be mo
253c0 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67  nitored.** using
253d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72   the [sqlite3_tr
253e0 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e  ace_v2()] tracin
253f0 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68  g logic.  The th
25400 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
25410 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
25420 65 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52  e_v2()] is an OR
25430 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  -ed combination 
25440 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  of one or more o
25450 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
25460 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e  ng constants.  ^
25470 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
25480 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
25490 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f  callback.** is o
254a0 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
254b0 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a  ing constants..*
254c0 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67  *.** New tracing
254d0 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62   constants may b
254e0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
254f0 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  e releases..**.*
25500 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62  * ^A trace callb
25510 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67  ack has four arg
25520 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63  uments: xCallbac
25530 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e  k(T,C,P,X)..** ^
25540 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69  The T argument i
25550 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74  s one of the int
25560 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20  eger type codes 
25570 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43  above..** ^The C
25580 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63   argument is a c
25590 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
255a0 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  xt pointer passe
255b0 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
255c0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
255d0 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
255e0 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50  _v2()]..** The P
255f0 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73   and X arguments
25600 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68   are pointers wh
25610 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70  ose meanings dep
25620 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20  end on T..**.** 
25630 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
25640 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64  _TRACE_STMT]] <d
25650 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  t>SQLITE_TRACE_S
25660 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TMT</dt>.** <dd>
25670 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
25680 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69  _STMT callback i
25690 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
256a0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
256b0 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67  ent.** first beg
256c0 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20  ins running and 
256d0 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65  possibly at othe
256e0 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74  r times during t
256f0 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20  he.** execution 
25700 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20  of the prepared 
25710 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20  statement, such 
25720 61 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20  as at the start 
25730 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67  of each.** trigg
25740 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e  er subprogram. ^
25750 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
25760 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
25770 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
25780 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65  statement]. ^The
25790 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   X argument is a
257a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
257b0 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73  ring which.** is
257c0 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20   the unexpanded 
257d0 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20  SQL text of the 
257e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
257f0 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d  nt or an SQL com
25800 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e  ment .** that in
25810 64 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f  dicates the invo
25820 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67  cation of a trig
25830 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62  ger.  ^The callb
25840 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a  ack can compute.
25850 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74  ** the same text
25860 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
25870 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62   been returned b
25880 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  y the legacy [sq
25890 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a  lite3_trace()].*
258a0 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75  * interface by u
258b0 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d  sing the X argum
258c0 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e  ent when X begin
258d0 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20  s with "--" and 
258e0 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c  invoking.** [sql
258f0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
25900 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e  l(P)] otherwise.
25910 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25920 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20  TRACE_PROFILE]] 
25930 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
25940 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a  _PROFILE</dt>.**
25950 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
25960 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61  TRACE_PROFILE ca
25970 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20  llback provides 
25980 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68  approximately th
25990 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d  e same.** inform
259a0 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76  ation as is prov
259b0 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ided by the [sql
259c0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20  ite3_profile()] 
259d0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  callback..** ^Th
259e0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
259f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
25a00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25a10 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  ment] and the.**
25a20 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e   X argument poin
25a30 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69  ts to a 64-bit i
25a40 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
25a50 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66  the estimated of
25a60 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
25a70 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61  f nanosecond tha
25a80 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
25a90 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
25aa0 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51   run..** ^The SQ
25ab0 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
25ac0 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  LE callback is i
25ad0 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
25ae0 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
25af0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  es..**.** [[SQLI
25b00 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c  TE_TRACE_ROW]] <
25b10 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
25b20 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ROW</dt>.** <dd>
25b30 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
25b40 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73  _ROW callback is
25b50 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
25b60 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  r a prepared.** 
25b70 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61  statement genera
25b80 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77  tes a single row
25b90 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a   of result.  .**
25ba0 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
25bb0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
25bc0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25bd0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68  tatement] and th
25be0 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20  e.** X argument 
25bf0 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  is unused..**.**
25c00 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
25c10 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CLOSE]] <dt>SQLI
25c20 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f  TE_TRACE_CLOSE</
25c30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
25c40 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
25c50 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  E callback is in
25c60 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74  voked when a dat
25c70 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
25c80 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e  ion closes..** ^
25c90 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
25ca0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
25cb0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
25cc0 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a  nection] object.
25cd0 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67  ** and the X arg
25ce0 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e  ument is unused.
25cf0 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
25d00 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
25d10 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30  E_STMT       0x0
25d20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
25d30 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20  _TRACE_PROFILE  
25d40 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53    0x02.#define S
25d50 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20  QLITE_TRACE_ROW 
25d60 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66         0x04.#def
25d70 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
25d80 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38  _CLOSE      0x08
25d90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25da0 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b  : SQL Trace Hook
25db0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
25dc0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
25dd0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
25de0 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,M,X,P) interfa
25df0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74  ce registers a t
25e00 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  race callback.**
25e10 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69   function X agai
25e20 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f  nst [database co
25e30 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69  nnection] D, usi
25e40 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b  ng property mask
25e50 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78   M.** and contex
25e60 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49  t pointer P.  ^I
25e70 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b  f the X callback
25e80 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69   is.** NULL or i
25e90 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20  f the M mask is 
25ea0 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69  zero, then traci
25eb0 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  ng is disabled. 
25ec0 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65   The.** M argume
25ed0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
25ee0 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63   bitwise OR-ed c
25ef0 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
25f00 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53   zero or more [S
25f10 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e  QLITE_TRACE] con
25f20 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45  stants..**.** ^E
25f30 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68  ach call to eith
25f40 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  er sqlite3_trace
25f50 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72  () or sqlite3_tr
25f60 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64  ace_v2() overrid
25f70 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29  es .** (cancels)
25f80 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73   any prior calls
25f90 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63   to sqlite3_trac
25fa0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74  e() or sqlite3_t
25fb0 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  race_v2()..**.**
25fc0 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b   ^The X callback
25fd0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
25fe0 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20  ever any of the 
25ff0 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65  events identifie
26000 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20  d by .** mask M 
26010 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74  occur.  ^The int
26020 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75  eger return valu
26030 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62  e from the callb
26040 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ack is currently
26050 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f  .** ignored, tho
26060 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61  ugh this may cha
26070 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65  nge in future re
26080 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63  leases.  Callbac
26090 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  k.** implementat
260a0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75  ions should retu
260b0 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72  rn zero to ensur
260c0 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69  e future compati
260d0 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
260e0 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
260f0 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
26100 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20  four arguments: 
26110 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58  callback(T,C,P,X
26120 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67  )..** ^The T arg
26130 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
26140 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  the [SQLITE_TRAC
26150 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20  E].** constants 
26160 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20  to indicate why 
26170 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73  the callback was
26180 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68   invoked..** ^Th
26190 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e C argument is 
261a0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
261b0 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  ntext pointer..*
261c0 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72  * The P and X ar
261d0 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e  guments are poin
261e0 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69  ters whose meani
261f0 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e  ngs depend on T.
26200 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
26210 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e  e3_trace_v2() in
26220 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e  terface is inten
26230 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74  ded to replace t
26240 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
26250 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
26260 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73  _trace()] and [s
26270 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
26280 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68  ], both of which
26290 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74  .** are deprecat
262a0 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
262b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  I int sqlite3_tr
262c0 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ace_v2(.  sqlite
262d0 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75  3*,.  unsigned u
262e0 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61  Mask,.  int(*xCa
262f0 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64  llback)(unsigned
26300 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69  ,void*,void*,voi
26310 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74  d*),.  void *pCt
26320 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x.);../*.** CAPI
26330 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
26340 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
26350 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
26360 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
26370 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
26380 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
26390 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
263a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
263b0 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
263c0 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
263d0 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
263e0 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
263f0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
26400 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
26410 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
26420 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
26430 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
26440 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
26450 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
26460 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
26470 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
26480 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
26490 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
264a0 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
264b0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
264c0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
264d0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
264e0 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
264f0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
26500 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
26510 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70  eter N is the ap
26520 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72  proximate number
26530 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
26540 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
26550 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
26560 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
26570 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
26580 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
26590 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20  he callback X.  
265a0 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
265b0 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20  an one then the 
265c0 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64  progress.** hand
265d0 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ler is disabled.
265e0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
265f0 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
26600 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
26610 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
26620 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
26630 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
26640 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
26650 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
26660 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
26670 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
26680 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
26690 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
266a0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
266b0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
266c0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
266d0 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
266e0 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
266f0 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
26700 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
26710 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
26720 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
26730 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
26740 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
26750 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
26760 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
26770 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
26780 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
26790 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
267a0 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
267b0 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
267c0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
267d0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
267e0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
267f0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
26800 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
26810 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
26820 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
26830 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
26840 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
26850 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
26860 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
26870 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
26880 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
26890 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
268a0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
268b0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
268c0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
268d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
268e0 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
268f0 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
26900 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
26910 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
26920 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26930 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
26940 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
26950 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  tion.** CONSTRUC
26960 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  TOR: sqlite3.**.
26970 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
26980 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
26990 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
269a0 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
269b0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
269c0 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
269d0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
269e0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
269f0 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
26a00 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
26a10 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
26a20 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
26a30 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
26a40 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
26a50 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
26a60 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
26a70 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
26a80 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
26a90 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
26aa0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
26ab0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
26ac0 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
26ad0 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
26ae0 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
26af0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
26b00 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
26b10 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
26b20 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
26b30 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
26b40 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
26b50 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
26b60 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
26b70 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
26b80 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
26b90 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
26ba0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
26bb0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
26bc0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
26bd0 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
26be0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
26bf0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
26c00 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
26c10 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
26c20 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
26c30 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
26c40 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
26c50 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
26c60 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
26c70 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
26c80 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
26c90 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
26ca0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
26cb0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
26cc0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
26cd0 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77  fault encoding w
26ce0 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72  ill be UTF-8 for
26cf0 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74   databases creat
26d00 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69  ed using.** sqli
26d10 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
26d20 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
26d30 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65    ^The default e
26d40 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61  ncoding for data
26d50 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  bases.** created
26d60 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f   using sqlite3_o
26d70 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20  pen16() will be 
26d80 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
26d90 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
26da0 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
26db0 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
26dc0 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
26dd0 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
26de0 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
26df0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
26e00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
26e10 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
26e20 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
26e30 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
26e40 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
26e50 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
26e60 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
26e70 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
26e80 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
26e90 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
26ea0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
26eb0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
26ec0 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
26ed0 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
26ee0 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
26ef0 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
26f00 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
26f10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
26f20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
26f30 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
26f40 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
26f50 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
26f60 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
26f70 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
26f80 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
26f90 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
26fa0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
26fb0 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
26fc0 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
26fd0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
26fe0 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
26ff0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
27000 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
27010 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
27020 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
27030 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
27040 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
27050 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
27060 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
27070 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
27080 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
27090 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
270a0 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
270b0 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
270c0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
270d0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
270e0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
270f0 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
27100 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
27110 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
27120 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
27130 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
27140 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
27150 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
27160 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
27170 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
27180 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
27190 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
271a0 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
271b0 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
271c0 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
271d0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
271e0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
271f0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
27200 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
27210 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
27220 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27230 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
27240 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
27250 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
27260 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
27270 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
27280 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
27290 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
272a0 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
272b0 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
272c0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
272d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
272e0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
272f0 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
27300 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
27310 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27320 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
27330 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
27340 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
27350 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
27360 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
27370 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
27380 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
27390 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
273a0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
273b0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
273c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
273d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
273e0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
273f0 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
27400 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
27410 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
27420 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
27430 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
27440 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
27450 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
27460 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
27470 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
27480 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
27490 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
274a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
274b0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
274c0 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
274d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
274e0 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
274f0 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
27500 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
27510 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
27520 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
27530 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
27540 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
27550 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
27560 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
27570 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
27580 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
27590 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
275a0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
275b0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
275c0 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
275d0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
275e0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
275f0 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
27600 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
27610 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
27620 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
27630 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
27640 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
27650 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
27660 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
27670 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
27680 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
27690 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
276a0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
276b0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
276c0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
276d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
276e0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
276f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
27700 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
27710 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
27720 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
27730 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
27740 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
27750 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
27760 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
27770 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
27780 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
27790 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
277a0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
277b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
277c0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
277d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
277e0 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
277f0 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
27800 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
27810 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
27820 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
27830 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
27840 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
27850 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
27860 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
27870 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
27880 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
27890 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
278a0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
278b0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
278c0 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
278d0 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
278e0 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
278f0 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
27900 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
27910 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
27920 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
27930 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
27940 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
27950 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
27960 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
27970 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
27980 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
27990 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
279a0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
279b0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
279c0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
279d0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
279e0 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
279f0 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
27a00 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
27a10 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
27a20 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
27a30 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
27a40 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
27a50 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
27a60 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
27a70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
27a80 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
27a90 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
27aa0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
27ab0 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
27ac0 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
27ad0 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
27ae0 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
27af0 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
27b00 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
27b10 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
27b20 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
27b30 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
27b40 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
27b50 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
27b60 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
27b70 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
27b80 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
27b90 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
27ba0 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
27bb0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
27bc0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
27bd0 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
27be0 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
27bf0 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
27c00 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
27c10 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
27c20 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
27c30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
27c40 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79  ()] method or by
27c50 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
27c60 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  _URI] compile-ti
27c70 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73  me option..** As
27c80 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
27c90 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69  on 3.7.7, URI fi
27ca0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
27cb0 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
27cc0 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
27cd0 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
27ce0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
27cf0 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
27d00 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
27d10 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
27d20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
27d30 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
27d40 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
27d50 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
27d60 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
27d70 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
27d80 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
27d90 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
27da0 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
27db0 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
27dc0 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
27dd0 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
27de0 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
27df0 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
27e00 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
27e10 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
27e20 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
27e30 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
27e40 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
27e50 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
27e60 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
27e70 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
27e80 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
27e90 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
27ea0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
27eb0 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
27ec0 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
27ed0 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
27ee0 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
27ef0 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
27f00 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
27f10 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
27f20 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
27f30 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
27f40 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
27f50 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
27f60 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
27f70 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
27f80 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
27f90 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
27fa0 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
27fb0 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
27fc0 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
27fd0 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
27fe0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
27ff0 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
28000 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e  th. .** ^(On win
28010 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
28020 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
28030 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
28040 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
28050 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
28060 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20   "C:").)^.**.** 
28070 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
28080 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
28090 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
280a0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
280b0 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
280c0 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
280d0 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
280e0 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
280f0 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
28100 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
28110 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
28120 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69  .** SQLite and i
28130 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53  ts built-in [VFS
28140 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68  es] interpret th
28150 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71  e.** following q
28160 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
28170 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
28180 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
28190 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
281a0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
281b0 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
281c0 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
281d0 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
281e0 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
281f0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
28200 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
28210 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
28220 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
28230 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
28240 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
28250 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
28260 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
28270 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
28280 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
28290 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
282a0 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
282b0 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
282c0 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
282d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
282e0 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
282f0 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
28300 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
28310 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
28320 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
28330 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
28340 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
28350 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
28360 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
28370 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
28380 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
28390 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
283a0 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
283b0 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
283c0 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
283d0 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a  her "ro", "rw",.
283e0 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72  **     "rwc", or
283f0 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d   "memory". Attem
28400 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
28410 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c  to any other val
28420 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20  ue is.**     an 
28430 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
28440 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
28450 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
28460 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
28470 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
28480 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
28490 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
284a0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
284b0 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
284c0 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
284d0 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
284e0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
284f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49  e3_open_v2(). ^I
28500 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
28510 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
28520 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
28530 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
28540 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
28550 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
28560 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
28570 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
28580 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
28590 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
285a0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
285b0 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
285c0 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
285d0 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
285e0 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
285f0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
28600 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
28610 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
28620 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
28630 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
28640 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
28650 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
28660 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
28670 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
28680 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
28690 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
286a0 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
286b0 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
286c0 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
286d0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
286e0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
286f0 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
28700 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
28710 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
28720 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
28730 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
28740 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
28750 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
28760 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
28770 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
28780 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
28790 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
287a0 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
287b0 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
287c0 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
287d0 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
287e0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
287f0 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
28800 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
28810 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
28820 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
28830 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
28840 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
28850 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
28860 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
28870 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
28880 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
28890 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
288a0 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
288b0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
288c0 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
288d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
288e0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
288f0 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
28900 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
28910 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
28920 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
28930 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
28940 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65  ehavior requeste
28950 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
28960 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
28970 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
28980 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
28990 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
289a0 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f  .**  <li> <b>pso
289b0 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77  w</b>: ^The psow
289c0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63   parameter indic
289d0 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20  ates whether or 
289e0 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b  not the.**     [
289f0 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72  powersafe overwr
28a00 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f  ite] property do
28a10 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61  es or does not a
28a20 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20  pply to the.**  
28a30 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61     storage media
28a40 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61   on which the da
28a50 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69  tabase file resi
28a60 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  des..**.**  <li>
28a70 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20   <b>nolock</b>: 
28a80 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61  ^The nolock para
28a90 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
28aa0 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  an query paramet
28ab0 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20  er.**     which 
28ac0 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20  if set disables 
28ad0 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20  file locking in 
28ae0 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
28af0 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a   modes.  This.**
28b00 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66       is useful f
28b10 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64  or accessing a d
28b20 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c  atabase on a fil
28b30 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65  esystem that doe
28b40 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70  s not.**     sup
28b50 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43  port locking.  C
28b60 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73  aution:  Databas
28b70 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67  e corruption mig
28b80 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f  ht result if two
28b90 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20  .**     or more 
28ba0 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20  processes write 
28bb0 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
28bc0 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65  base and any one
28bd0 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20   of those.**    
28be0 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20   processes uses 
28bf0 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20  nolock=1..**.** 
28c00 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62   <li> <b>immutab
28c10 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d  le</b>: ^The imm
28c20 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72  utable parameter
28c30 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
28c40 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d  ery.**     param
28c50 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61  eter that indica
28c60 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74  tes that the dat
28c70 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74  abase file is st
28c80 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72  ored on.**     r
28c90 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20  ead-only media. 
28ca0 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65   ^When immutable
28cb0 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20   is set, SQLite 
28cc0 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
28cd0 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65  .**     database
28ce0 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
28cf0 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79  changed, even by
28d00 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20   a process with 
28d10 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72  higher.**     pr
28d20 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20  ivilege, and so 
28d30 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
28d40 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79  opened read-only
28d50 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67   and all locking
28d60 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e  .**     and chan
28d70 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20  ge detection is 
28d80 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69  disabled.  Cauti
28d90 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20  on: Setting the 
28da0 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20  immutable.**    
28db0 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64   property on a d
28dc0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61  atabase file tha
28dd0 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63  t does in fact c
28de0 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74  hange can result
28df0 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72  .**     in incor
28e00 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c  rect query resul
28e10 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ts and/or [SQLIT
28e20 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72  E_CORRUPT] error
28e30 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c  s..**     See al
28e40 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  so: [SQLITE_IOCA
28e50 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a  P_IMMUTABLE]..**
28e60 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e         .** </ul>
28e70 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
28e80 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
28e90 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
28ea0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
28eb0 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
28ec0 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
28ed0 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
28ee0 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
28ef0 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
28f00 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
28f10 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
28f20 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
28f30 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
28f40 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
28f50 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
28f60 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
28f70 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
28f80 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
28f90 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
28fa0 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
28fb0 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
28fc0 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
28fd0 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
28fe0 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
28ff0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
29000 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
29010 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
29020 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
29030 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
29040 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
29050 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
29060 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
29070 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
29080 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
29090 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
290a0 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
290b0 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
290c0 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
290d0 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
290e0 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
290f0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
29100 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
29110 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
29120 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
29130 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
29140 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
29150 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
29160 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
29170 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
29180 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
29190 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
291a0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
291b0 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
291c0 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
291d0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
291e0 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
291f0 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
29200 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
29210 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
29220 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
29230 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
29240 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
29250 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
29260 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
29270 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
29280 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
29290 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
292a0 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
292b0 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
292c0 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
292d0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
292e0 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
292f0 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
29300 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
29310 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
29320 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
29330 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
29340 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
29350 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
29360 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
29370 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
29380 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
29390 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
293a0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
293b0 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
293c0 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
293d0 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
293e0 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
293f0 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
29400 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
29410 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
29420 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69  b?vfs=unix-dotfi
29430 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  le <td>.**      
29440 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
29450 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
29460 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
29470 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f  ial VFS "unix-do
29480 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20  tfile".**       
29490 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74     that uses dot
294a0 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20  -files in place 
294b0 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72  of posix advisor
294c0 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74  y locking..** <t
294d0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
294e0 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
294f0 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
29500 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
29510 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
29520 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
29530 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
29540 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
29550 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
29560 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
29570 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
29580 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
29590 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
295a0 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
295b0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
295c0 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
295d0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
295e0 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
295f0 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
29600 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
29610 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
29620 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
29630 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
29640 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
29650 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
29660 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
29670 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
29680 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
29690 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
296a0 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
296b0 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
296c0 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
296d0 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
296e0 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
296f0 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
29700 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
29710 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
29720 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
29730 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
29740 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
29750 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
29760 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
29770 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
29780 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
29790 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
297a0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
297b0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
297c0 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
297d0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
297e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
297f0 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
29800 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
29810 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
29820 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
29830 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
29840 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
29850 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
29860 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
29870 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
29880 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
29890 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
298a0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
298b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
298c0 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
298d0 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
298e0 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
298f0 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
29900 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
29910 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
29920 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  ling sqlite3_ope
29930 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
29940 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72  pen_v2().  Other
29950 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
29960 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
29970 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
29980 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
29990 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  s may fail..**.*
299a0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
299b0 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
299c0 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ory].*/.SQLITE_A
299d0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
299e0 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
299f0 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
29a00 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
29a10 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
29a20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
29a30 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
29a40 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
29a50 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
29a60 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
29a70 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
29a80 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
29a90 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
29aa0 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
29ab0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
29ac0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
29ad0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
29ae0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  ndle */.);.SQLIT
29af0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
29b00 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
29b10 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
29b20 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
29b30 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
29b40 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
29b50 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
29b60 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
29b70 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
29b80 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
29b90 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
29ba0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
29bb0 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
29bc0 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
29bd0 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
29be0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
29bf0 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72  btain Values For
29c00 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a   URI Parameters.
29c10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
29c20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73  utility routines
29c30 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20  , useful to VFS 
29c40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c  implementations,
29c50 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74   that check.** t
29c60 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62  o see if a datab
29c70 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55  ase file was a U
29c80 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65  RI that containe
29c90 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65  d a specific que
29ca0 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ry .** parameter
29cb0 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61  , and if so obta
29cc0 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ins the value of
29cd0 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61   that query para
29ce0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
29cf0 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  F is the databas
29d00 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
29d10 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
29d20 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f  he xOpen() metho
29d30 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69  d of .** a VFS i
29d40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
29d50 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  en the flags par
29d60 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28  ameter to xOpen(
29d70 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a  ) has one or .**
29d80 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51   more of the [SQ
29d90 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f  LITE_OPEN_URI] o
29da0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  r [SQLITE_OPEN_M
29db0 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74  AIN_DB] bits set
29dc0 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65   and.** P is the
29dd0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65   name of the que
29de0 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ry parameter, th
29df0 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  en.** sqlite3_ur
29e00 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
29e10 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
29e20 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70  ue of the P.** p
29e30 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65  arameter if it e
29e40 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20  xists or a NULL 
29e50 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65  pointer if P doe
29e60 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20  s not appear as 
29e70 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  a .** query para
29e80 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20  meter on F.  If 
29e90 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72  P is a query par
29ea0 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68  ameter of F.** h
29eb0 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76  as no explicit v
29ec0 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  alue, then sqlit
29ed0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
29ee0 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a  (F,P) returns.**
29ef0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
29f00 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
29f10 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
29f20 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
29f30 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75  ,B) routine assu
29f40 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20  mes that P is a 
29f50 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d  boolean.** param
29f60 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
29f70 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c   true (1) or fal
29f80 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67  se (0) according
29f90 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a   to the value.**
29fa0 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69   of P.  The sqli
29fb0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
29fc0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72  F,P,B) routine r
29fd0 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
29fe0 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  if the.** value 
29ff0 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  of query paramet
2a000 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
2a010 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72  yes", "true", or
2a020 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20   "on" in any.** 
2a030 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76  case or if the v
2a040 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
2a050 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62   a non-zero numb
2a060 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c  er.  The .** sql
2a070 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
2a080 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73  (F,P,B) routines
2a090 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28   returns false (
2a0a0 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  0) if the value 
2a0b0 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  of.** query para
2a0c0 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
2a0d0 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c  f "no", "false",
2a0e0 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79   or "off" in any
2a0f0 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74   case or.** if t
2a100 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
2a110 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a  with a numeric z
2a120 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f  ero.  If P is no
2a130 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  t a query.** par
2a140 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69  ameter on F or i
2a150 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
2a160 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74   is does not mat
2a170 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a  ch any of the.**
2a180 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c   above, then sql
2a190 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
2a1a0 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
2a1b0 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  (B!=0)..**.** Th
2a1c0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  e sqlite3_uri_in
2a1d0 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69  t64(F,P,D) routi
2a1e0 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20  ne converts the 
2a1f0 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20  value of P into 
2a200 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e  a.** 64-bit sign
2a210 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72  ed integer and r
2a220 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65  eturns that inte
2a230 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64  ger, or D if P d
2a240 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74  oes not.** exist
2a250 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  .  If the value 
2a260 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e  of P is somethin
2a270 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20  g other than an 
2a280 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a  integer, then.**
2a290 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
2a2a0 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69  d..** .** If F i
2a2b0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2a2c0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
2a2d0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
2a2e0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
2a2f0 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  nd.** sqlite3_ur
2a300 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
2a310 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20   returns B.  If 
2a320 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20  F is not a NULL 
2a330 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69  pointer and.** i
2a340 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
2a350 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70   file pathname p
2a360 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69  ointer that SQLi
2a370 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  te passed into t
2a380 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20  he xOpen.** VFS 
2a390 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65  method, then the
2a3a0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
2a3b0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64  s routine is und
2a3c0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2a3d0 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  bly.** undesirab
2a3e0 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  le..*/.SQLITE_AP
2a3f0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2a400 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
2a410 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ter(const char *
2a420 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74  zFilename, const
2a430 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a   char *zParam);.
2a440 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2a450 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
2a460 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
2a470 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
2a480 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
2a490 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f  efault);.SQLITE_
2a4a0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
2a4b0 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  4 sqlite3_uri_in
2a4c0 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t64(const char*,
2a4d0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
2a4e0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a  lite3_int64);...
2a4f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2a500 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
2a510 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48  Messages.** METH
2a520 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
2a530 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2a540 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20  ecent sqlite3_* 
2a550 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61  API call associa
2a560 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61  ted with .** [da
2a570 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a580 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65  n] D failed, the
2a590 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72  n the sqlite3_er
2a5a0 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61  rcode(D) interfa
2a5b0 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  ce.** returns th
2a5c0 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
2a5d0 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65  t code] or [exte
2a5e0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
2a5f0 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50  ] for that.** AP
2a600 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68  I call..** If th
2a610 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  e most recent AP
2a620 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65  I call was succe
2a630 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74  ssful,.** then t
2a640 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2a650 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72  from sqlite3_err
2a660 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69  code() is undefi
2a670 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ned..** ^The sql
2a680 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
2a690 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72  rcode().** inter
2a6a0 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65  face is the same
2a6b0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
2a6c0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
2a6d0 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  he .** [extended
2a6e0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76   result code] ev
2a6f0 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64  en when extended
2a700 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
2a710 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a  e.** disabled..*
2a720 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2a730 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
2a740 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
2a750 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
2a760 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
2a770 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
2a780 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
2a790 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
2a7a0 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65  TF-16 respective
2a7b0 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  ly..** ^(Memory 
2a7c0 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
2a7d0 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
2a7e0 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
2a7f0 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
2a800 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
2a810 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
2a820 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
2a830 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
2a840 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
2a850 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
2a860 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
2a870 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
2a880 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
2a890 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
2a8a0 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
2a8b0 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a  nctions.)^.**.**
2a8c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
2a8d0 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65  rstr() interface
2a8e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67   returns the Eng
2a8f0 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
2a900 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72  xt.** that descr
2a910 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74  ibes the [result
2a920 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38   code], as UTF-8
2a930 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
2a940 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
2a950 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
2a960 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
2a970 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74  ally.** and must
2a980 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79   not be freed by
2a990 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2a9a0 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  )^..**.** When t
2a9b0 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
2a9c0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
2a9d0 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
2a9e0 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
2a9f0 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
2aa00 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
2aa10 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
2aa20 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
2aa30 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
2aa40 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
2aa50 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
2aa60 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
2aa70 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
2aa80 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
2aa90 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
2aaa0 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
2aab0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
2aac0 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
2aad0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
2aae0 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
2aaf0 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
2ab00 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
2ab10 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
2ab20 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2ab30 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
2ab40 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
2ab50 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
2ab60 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
2ab70 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
2ab80 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
2ab90 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
2aba0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
2abb0 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
2abc0 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
2abd0 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
2abe0 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
2abf0 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
2ac00 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
2ac10 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
2ac20 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
2ac30 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
2ac40 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
2ac50 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
2ac60 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
2ac70 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
2ac80 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
2ac90 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
2aca0 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
2acb0 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
2acc0 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53  not be set..*/.S
2acd0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2ace0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
2acf0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
2ad00 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2ad10 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
2ad20 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
2ad30 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2ad40 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2ad50 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
2ad60 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2ad70 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2ad80 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
2ad90 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  e3*);.SQLITE_API
2ada0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2adb0 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
2adc0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2add0 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74  F: Prepared Stat
2ade0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
2adf0 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
2ae00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
2ae10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ae20 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
2ae30 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
2ae40 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
2ae50 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
2ae60 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20  atement that.** 
2ae70 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65  has been compile
2ae80 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f  d into binary fo
2ae90 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20  rm and is ready 
2aea0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e  to be evaluated.
2aeb0 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20  .**.** Think of 
2aec0 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
2aed0 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65  nt as a separate
2aee0 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61   computer progra
2aef0 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69  m.  The.** origi
2af00 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20  nal SQL text is 
2af10 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20  source code.  A 
2af20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2af30 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73  nt object .** is
2af40 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62   the compiled ob
2af50 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20  ject code.  All 
2af60 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  SQL must be conv
2af70 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20  erted into a.** 
2af80 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2af90 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e  nt before it can
2afa0 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54   be run..**.** T
2afb0 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66  he life-cycle of
2afc0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2afd0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75  ement object usu
2afe0 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74  ally goes like t
2aff0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
2b000 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
2b010 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2b020 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69  ement object usi
2b030 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
2b040 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c  are_v2()]..** <l
2b050 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
2b060 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75  o [parameters] u
2b070 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2b080 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
2b090 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
2b0a0 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
2b0b0 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
2b0c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
2b0d0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
2b0e0 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
2b0f0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2b100 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
2b110 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
2b120 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
2b130 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
2b140 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
2b150 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
2b160 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
2b170 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
2b180 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2b190 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79  ..** </ol>.*/.ty
2b1a0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2b1b0 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
2b1c0 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
2b1d0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
2b1e0 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48  e Limits.** METH
2b1f0 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
2b200 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
2b210 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
2b220 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
2b230 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
2b240 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
2b250 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
2b260 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
2b270 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2b280 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
2b290 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b2a0 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
2b2b0 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
2b2c0 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
2b2d0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2b2e0 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
2b2f0 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
2b300 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
2b310 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
2b320 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
2b330 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
2b340 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2b350 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
2b360 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
2b370 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
2b380 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
2b390 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
2b3a0 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
2b3b0 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
2b3c0 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
2b3d0 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
2b3e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
2b3f0 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
2b400 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
2b410 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
2b420 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
2b430 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
2b440 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
2b450 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
2b460 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
2b470 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
2b480 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
2b490 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
2b4a0 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
2b4b0 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
2b4c0 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
2b4d0 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
2b4e0 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
2b4f0 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
2b500 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
2b510 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
2b520 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
2b530 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2b540 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
2b550 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
2b560 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
2b570 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
2b580 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2b590 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
2b5a0 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
2b5b0 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
2b5c0 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
2b5d0 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
2b5e0 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
2b5f0 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
2b600 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
2b610 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
2b620 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
2b630 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
2b640 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
2b650 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
2b660 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
2b670 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
2b680 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
2b690 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
2b6a0 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
2b6b0 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
2b6c0 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
2b6d0 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
2b6e0 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
2b6f0 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
2b700 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
2b710 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
2b720 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
2b730 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
2b740 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
2b750 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
2b760 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
2b770 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
2b780 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
2b790 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
2b7a0 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
2b7b0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
2b7c0 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
2b7d0 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
2b7e0 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
2b7f0 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
2b800 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
2b810 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
2b820 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
2b830 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
2b840 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
2b850 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
2b860 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
2b870 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
2b880 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
2b890 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
2b8a0 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
2b8b0 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
2b8c0 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
2b8d0 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
2b8e0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
2b8f0 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
2b900 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
2b910 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
2b920 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
2b930 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
2b940 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
2b950 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
2b960 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
2b970 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
2b980 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
2b990 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ases..*/.SQLITE_
2b9a0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2b9b0 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
2b9c0 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
2b9d0 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
2b9e0 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
2b9f0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
2ba00 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
2ba10 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
2ba20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
2ba30 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
2ba40 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
2ba50 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
2ba60 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
2ba70 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
2ba80 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
2ba90 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
2baa0 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
2bab0 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
2bac0 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
2bad0 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
2bae0 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
2baf0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2bb00 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
2bb10 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
2bb20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
2bb30 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
2bb40 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2bb50 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
2bb60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2bb70 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2bb80 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
2bb90 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
2bba0 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
2bbb0 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
2bbc0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2bbd0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
2bbe0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
2bbf0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
2bc00 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
2bc10 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
2bc20 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
2bc30 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
2bc40 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2bc50 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
2bc60 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
2bc70 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
2bc80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2bc90 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2bca0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
2bcb0 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
2bcc0 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
2bcd0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2bce0 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
2bcf0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2bd00 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
2bd10 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
2bd20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
2bd30 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
2bd40 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2bd50 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
2bd60 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
2bd70 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
2bd80 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
2bd90 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
2bda0 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
2bdb0 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
2bdc0 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
2bdd0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2bde0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
2bdf0 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
2be00 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
2be10 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
2be20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2be30 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
2be40 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
2be50 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
2be60 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2be70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
2be80 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
2be90 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
2bea0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2beb0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2bec0 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
2bed0 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
2bee0 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
2bef0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
2bf00 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
2bf10 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
2bf20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
2bf30 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
2bf40 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
2bf50 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
2bf60 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
2bf70 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
2bf80 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2bf90 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2bfa0 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
2bfb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2bfc0 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
2bfd0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2bfe0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2bff0 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
2c000 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
2c010 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2c020 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
2c030 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
2c040 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
2c050 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2c060 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
2c070 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
2c080 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
2c090 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2c0a0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
2c0b0 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
2c0c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2c0d0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
2c0e0 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
2c0f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
2c100 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
2c110 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
2c120 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
2c130 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
2c140 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2c150 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2c160 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
2c170 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
2c180 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2c190 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
2c1a0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
2c1b0 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
2c1c0 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
2c1d0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2c1e0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
2c1f0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
2c200 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
2c210 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
2c220 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
2c230 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2c240 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
2c250 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
2c260 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
2c270 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  [[SQLITE_LIMIT_W
2c280 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20  ORKER_THREADS]] 
2c290 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2c2a0 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
2c2b0 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  S</dt>.** <dd>Th
2c2c0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2c2d0 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f   of auxiliary wo
2c2e0 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61  rker threads tha
2c2f0 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70  t a single.** [p
2c300 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c310 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64  t] may start.</d
2c320 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
2c330 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c340 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
2c350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c360 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
2c370 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
2c380 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
2c390 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2c3a0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
2c3b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c3c0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2c3d0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
2c3e0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
2c3f0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2c400 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
2c410 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
2c420 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2c430 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
2c440 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
2c450 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
2c460 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2c470 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
2c480 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
2c490 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
2c4a0 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
2c4b0 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
2c4c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
2c4d0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
2c4e0 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
2c4f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
2c500 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
2c510 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
2c520 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2c530 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
2c540 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
2c550 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2c560 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20  _WORKER_THREADS 
2c570 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a            11../*
2c580 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2c590 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
2c5a0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
2c5b0 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
2c5c0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
2c5d0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2c5e0 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  3.** CONSTRUCTOR
2c5f0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2c600 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
2c610 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
2c620 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
2c630 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
2c640 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
2c650 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
2c660 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2c670 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
2c680 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
2c690 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
2c6a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
2c6b0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
2c6c0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
2c6d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2c6e0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2c6f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
2c700 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2c710 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
2c720 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c730 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
2c740 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
2c750 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
2c760 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
2c770 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
2c780 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
2c790 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
2c7a0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
2c7b0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
2c7c0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
2c7d0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2c7e0 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
2c7f0 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
2c800 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2c810 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
2c820 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2c830 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
2c840 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
2c850 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
2c860 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2c870 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
2c880 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
2c890 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2c8a0 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f   ^If nByte is po
2c8b0 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  sitive, then it 
2c8c0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2c8d0 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66   of bytes read f
2c8e0 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e  rom zSql.  ^If n
2c8f0 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68  Byte is zero, th
2c900 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a  en no prepared.*
2c910 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67  * statement is g
2c920 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20  enerated..** If 
2c930 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
2c940 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
2c950 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
2c960 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
2c970 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20  n.** there is a 
2c980 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63  small performanc
2c990 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70  e advantage to p
2c9a0 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
2c9b0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
2c9c0 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
2c9d0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2c9e0 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
2c9f0 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
2ca00 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
2ca10 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  tor..**.** ^If p
2ca20 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
2ca30 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
2ca40 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
2ca50 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
2ca60 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
2ca70 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
2ca80 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
2ca90 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
2caa0 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
2cab0 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
2cac0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
2cad0 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
2cae0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
2caf0 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
2cb00 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
2cb10 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
2cb20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
2cb30 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
2cb40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2cb50 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
2cb60 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
2cb70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
2cb80 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
2cb90 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
2cba0 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
2cbb0 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
2cbc0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
2cbd0 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
2cbe0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
2cbf0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
2cc00 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
2cc10 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
2cc20 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
2cc30 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
2cc40 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
2cc50 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
2cc60 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
2cc70 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
2cc80 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2cc90 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
2cca0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2ccb0 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
2ccc0 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
2ccd0 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
2cce0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
2ccf0 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
2cd00 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
2cd10 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
2cd20 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
2cd30 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2cd40 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
2cd50 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2cd60 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
2cd70 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2cd80 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
2cd90 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
2cda0 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
2cdb0 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
2cdc0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
2cdd0 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
2cde0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
2cdf0 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
2ce00 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
2ce10 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
2ce20 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2ce30 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
2ce40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2ce50 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
2ce60 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2ce70 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
2ce80 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
2ce90 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
2cea0 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
2ceb0 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
2cec0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
2ced0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
2cee0 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
2cef0 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
2cf00 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
2cf10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
2cf20 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
2cf30 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
2cf40 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2cf50 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
2cf60 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
2cf70 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
2cf80 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
2cf90 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
2cfa0 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
2cfb0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
2cfc0 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
2cfd0 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51  . As many as [SQ
2cfe0 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f  LITE_MAX_SCHEMA_
2cff0 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65  RETRY].** retrie
2d000 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66  s will occur bef
2d010 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ore sqlite3_step
2d020 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20  () gives up and 
2d030 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72  returns an error
2d040 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
2d050 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
2d060 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
2d070 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2d080 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
2d090 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
2d0a0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
2d0b0 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
2d0c0 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
2d0d0 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2d0e0 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
2d0f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2d100 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
2d110 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
2d120 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
2d130 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
2d140 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
2d150 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
2d160 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
2d170 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2d180 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
2d190 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
2d1a0 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
2d1b0 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
2d1c0 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
2d1d0 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
2d1e0 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
2d1f0 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
2d200 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
2d210 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
2d220 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
2d230 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
2d240 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
2d250 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
2d260 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
2d270 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
2d280 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
2d290 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
2d2a0 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
2d2b0 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
2d2c0 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
2d2d0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2d2e0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
2d2f0 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
2d300 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
2d310 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
2d320 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
2d330 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
2d340 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
2d350 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
2d360 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
2d370 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
2d380 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
2d390 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
2d3a0 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
2d3b0 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
2d3c0 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
2d3d0 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
2d3e0 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
2d3f0 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
2d400 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2d410 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
2d420 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
2d430 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
2d440 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
2d450 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
2d460 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
2d470 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
2d480 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
2d490 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
2d4a0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2d4b0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
2d4c0 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
2d4d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2d4e0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2d4f0 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
2d500 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2d510 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2d520 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2d530 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2d540 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2d550 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2d560 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2d570 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2d580 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2d590 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2d5a0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2d5b0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2d5c0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2d5d0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2d5e0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2d5f0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2d600 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2d610 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2d620 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2d630 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d640 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
2d650 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2d660 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2d670 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2d680 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2d690 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2d6a0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2d6b0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2d6c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2d6d0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2d6e0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2d6f0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2d700 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2d710 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2d720 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2d730 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2d740 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2d750 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2d760 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2d770 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2d780 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2d790 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
2d7a0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2d7b0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2d7c0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2d7d0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2d7e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2d7f0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2d800 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2d810 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2d820 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2d830 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2d840 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2d850 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2d860 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2d870 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2d880 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
2d890 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2d8a0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2d8b0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2d8c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2d8d0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2d8e0 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
2d8f0 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2d900 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2d910 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2d920 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2d930 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2d940 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2d950 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2d960 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2d970 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2d980 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2d990 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2d9a0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2d9b0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2d9c0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2d9d0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2d9e0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2d9f0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2da00 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2da10 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2da20 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
2da30 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
2da40 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2da50 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2da60 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  The sqlite3_sql(
2da70 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2da80 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2da90 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  o a copy of the 
2daa0 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78  UTF-8.** SQL tex
2dab0 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
2dac0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2dad0 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73  ment] P if P was
2dae0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 65  .** created by e
2daf0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2db00 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2db10 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2db20 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68  16_v2()]..** ^Th
2db30 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  e sqlite3_expand
2db40 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  ed_sql(P) interf
2db50 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2db60 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38  inter to a UTF-8
2db70 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
2db80 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65  ining the SQL te
2db90 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73  xt of prepared s
2dba0 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a  tatement P with.
2dbb0 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  ** [bound parame
2dbc0 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a  ters] expanded..
2dbd0 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2dbe0 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72  ple, if a prepar
2dbf0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2dc00 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68  created using th
2dc10 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53  e SQL.** text "S
2dc20 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22  ELECT $abc,:xyz"
2dc30 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65   and if paramete
2dc40 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20  r $abc is bound 
2dc50 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a  to integer 2345.
2dc60 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72  ** and parameter
2dc70 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64   :xyz is unbound
2dc80 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73  , then sqlite3_s
2dc90 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e  ql() will return
2dca0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
2dcb0 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54   string, "SELECT
2dcc0 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20   $abc,:xyz" but 
2dcd0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2dce0 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72  _sql().** will r
2dcf0 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33  eturn "SELECT 23
2dd00 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a  45,NULL".)^.**.*
2dd10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2dd20 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e  xpanded_sql() in
2dd30 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2dd40 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
2dd50 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69  ient memory.** i
2dd60 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68  s available to h
2dd70 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20  old the result, 
2dd80 6f 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74  or if the result
2dd90 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68   would exceed th
2dda0 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d  e.** the maximum
2ddb0 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64   string length d
2ddc0 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
2ddd0 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c   [SQLITE_LIMIT_L
2dde0 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ENGTH]..**.** ^T
2ddf0 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
2de00 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
2de10 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2de20 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65   limits the size
2de30 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72   of.** bound par
2de40 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e  ameter expansion
2de50 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  s.  ^The [SQLITE
2de60 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d  _OMIT_TRACE] com
2de70 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
2de80 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74  ion causes sqlit
2de90 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2dea0 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75  ) to always retu
2deb0 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  rn NULL..**.** ^
2dec0 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2ded0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  ned by sqlite3_s
2dee0 71 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64  ql(P) is managed
2def0 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69   by SQLite and i
2df00 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
2df10 6c 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68  ly freed when th
2df20 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2df30 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
2df40 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  d..** ^The strin
2df50 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2df60 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2df70 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74  ql(P), on the ot
2df80 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20  her hand,.** is 
2df90 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2dfa0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2dfb0 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65   and must be fre
2dfc0 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  e by the applica
2dfd0 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69  tion.** by passi
2dfe0 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
2dff0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 53 51  3_free()]..*/.SQ
2e000 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2e010 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
2e020 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2e030 53 74 6d 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  Stmt);.SQLITE_AP
2e040 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
2e050 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c  expanded_sql(sql
2e060 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2e070 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e080 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
2e090 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2e0a0 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
2e0b0 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a  abase.** METHOD:
2e0c0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2e0d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e0e0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
2e0f0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2e100 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2e110 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
2e120 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
2e130 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
2e140 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
2e150 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
2e160 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2e170 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
2e180 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2e190 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2e1a0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2e1b0 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
2e1c0 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
2e1d0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
2e1e0 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
2e1f0 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
2e200 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
2e210 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
2e220 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
2e230 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
2e240 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
2e250 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
2e260 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
2e270 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
2e280 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
2e290 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2e2a0 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
2e2b0 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
2e2c0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2e2d0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
2e2e0 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
2e2f0 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
2e300 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
2e310 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
2e320 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
2e330 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2e340 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
2e350 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2e360 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
2e370 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
2e380 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
2e390 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
2e3a0 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
2e3b0 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
2e3c0 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
2e3d0 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
2e3e0 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
2e3f0 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
2e400 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
2e410 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
2e420 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
2e430 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
2e440 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
2e450 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
2e460 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
2e470 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
2e480 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
2e490 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
2e4a0 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
2e4b0 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
2e4c0 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
2e4d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
2e4e0 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
2e4f0 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
2e500 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
2e510 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
2e520 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
2e530 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
2e540 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
2e550 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
2e560 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
2e570 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
2e580 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
2e590 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
2e5a0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
2e5b0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2e5c0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
2e5d0 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65  on disk..** ^The
2e5e0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2e5f0 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61  adonly() interfa
2e600 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2e610 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63  for [BEGIN] sinc
2e620 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72  e.** [BEGIN] mer
2e630 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61  ely sets interna
2e640 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65  l flags, but the
2e650 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d   [BEGIN|BEGIN IM
2e660 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20  MEDIATE] and.** 
2e670 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43  [BEGIN|BEGIN EXC
2e680 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73  LUSIVE] commands
2e690 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61   do touch the da
2e6a0 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a  tabase and so.**
2e6b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2e6c0 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73  adonly() returns
2e6d0 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65   false for those
2e6e0 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 53 51   commands..*/.SQ
2e6f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2e700 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2e710 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ly(sqlite3_stmt 
2e720 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2e730 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
2e740 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65  ine If A Prepare
2e750 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20  d Statement Has 
2e760 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45  Been Reset.** ME
2e770 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2e780 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2e790 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2e7a0 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
2e7b0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
2e7c0 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b  ero) if the.** [
2e7d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e7e0 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73  nt] S has been s
2e7f0 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20  tepped at least 
2e800 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  once using .** [
2e810 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2e820 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72   but has neither
2e830 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
2e840 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20  on (returned.** 
2e850 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72  [SQLITE_DONE] fr
2e860 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  om [sqlite3_step
2e870 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65  (S)]) nor.** bee
2e880 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
2e890 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2e8a0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2e8b0 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
2e8c0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2e8d0 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
2e8e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
2e8f0 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
2e900 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2e910 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
2e920 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
2e930 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e940 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
2e950 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2e960 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
2e970 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
2e980 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
2e990 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2e9a0 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
2e9b0 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
2e9c0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
2e9d0 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
2e9e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e9f0 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
2ea00 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
2ea10 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
2ea20 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
2ea30 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
2ea40 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
2ea50 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
2ea60 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
2ea70 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
2ea80 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
2ea90 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
2eaa0 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
2eab0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
2eac0 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  en..*/.SQLITE_AP
2ead0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
2eae0 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f  mt_busy(sqlite3_
2eaf0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2eb00 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
2eb10 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
2eb20 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
2eb30 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
2eb40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
2eb50 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2eb60 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
2eb70 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
2eb80 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2eb90 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
2eba0 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
2ebb0 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
2ebc0 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
2ebd0 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
2ebe0 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
2ebf0 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
2ec00 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
2ec10 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
2ec20 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
2ec30 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
2ec40 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
2ec50 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2ec60 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
2ec70 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
2ec80 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
2ec90 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
2eca0 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
2ecb0 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
2ecc0 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
2ecd0 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
2ece0 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
2ecf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
2ed00 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
2ed10 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
2ed20 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
2ed30 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
2ed40 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2ed50 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
2ed60 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
2ed70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
2ed80 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
2ed90 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
2eda0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
2edb0 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
2edc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54  qlite3_value.  T
2edd0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
2ede0 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65  alue_dup()] inte
2edf0 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
2ee00 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61  d to construct a
2ee10 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74   new .** protect
2ee20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2ee30 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65   from an unprote
2ee40 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2ee50 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
2ee60 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
2ee70 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
2ee80 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
2ee90 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
2eea0 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
2eeb0 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  n internal mutex
2eec0 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
2eed0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2eee0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2eef0 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
2ef00 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
2ef10 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2ef20 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2ef30 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
2ef40 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
2ef50 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
2ef60 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
2ef70 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
2ef80 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
2ef90 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
2efa0 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
2efb0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
2efc0 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
2efd0 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
2efe0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
2eff0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
2f000 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
2f010 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
2f020 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
2f030 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
2f040 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
2f050 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
2f060 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2f070 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
2f080 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
2f090 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
2f0a0 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
2f0b0 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
2f0c0 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
2f0d0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
2f0e0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
2f0f0 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
2f100 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2f110 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2f120 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2f130 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2f140 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
2f150 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
2f160 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
2f170 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
2f180 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
2f190 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
2f1a0 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
2f1b0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
2f1c0 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
2f1d0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2f1e0 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
2f1f0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
2f200 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2f210 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2f220 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2f230 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2f240 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
2f250 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
2f260 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2f270 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
2f280 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
2f290 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2f2a0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2f2b0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
2f2c0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
2f2d0 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
2f2e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
2f2f0 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
2f300 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2f310 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
2f320 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2f330 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
2f340 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74  struct Mem sqlit
2f350 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a  e3_value;../*.**
2f360 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46   CAPI3REF: SQL F
2f370 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20  unction Context 
2f380 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
2f390 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63   context in whic
2f3a0 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f  h an SQL functio
2f3b0 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74  n executes is st
2f3c0 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71  ored in an.** sq
2f3d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
2f3e0 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65  ject.  ^A pointe
2f3f0 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f  r to an sqlite3_
2f400 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a  context object.*
2f410 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73  * is always firs
2f420 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  t parameter to [
2f430 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f440 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2f450 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  s]..** The appli
2f460 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2f470 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
2f480 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20  ementation will 
2f490 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69  pass this.** poi
2f4a0 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74  nter through int
2f4b0 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  o calls to [sqli
2f4c0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c  te3_result_int |
2f4d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28   sqlite3_result(
2f4e0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2f4f0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2f500 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75  t()], [sqlite3_u
2f510 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20  ser_data()],.** 
2f520 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
2f530 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b  _db_handle()], [
2f540 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2f550 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  ata()],.** and/o
2f560 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  r [sqlite3_set_a
2f570 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79  uxdata()]..*/.ty
2f580 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2f590 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c  ite3_context sql
2f5a0 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f  ite3_context;../
2f5b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42  *.** CAPI3REF: B
2f5c0 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f  inding Values To
2f5d0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2f5e0 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ents.** KEYWORDS
2f5f0 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  : {host paramete
2f600 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  r} {host paramet
2f610 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ers} {host param
2f620 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45  eter name}.** KE
2f630 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72  YWORDS: {SQL par
2f640 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72  ameter} {SQL par
2f650 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65  ameters} {parame
2f660 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20  ter binding}.** 
2f670 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2f680 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  stmt.**.** ^(In 
2f690 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2f6a0 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20  t text input to 
2f6b0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f6c0 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76  _v2()] and its v
2f6d0 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65  ariants,.** lite
2f6e0 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c  rals may be repl
2f6f0 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d  aced by a [param
2f700 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68  eter] that match
2f710 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77  es one of follow
2f720 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73  ing.** templates
2f730 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2f740 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20  <li>  ?.** <li> 
2f750 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a   ?NNN.** <li>  :
2f760 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56  VVV.** <li>  @VV
2f770 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a  V.** <li>  $VVV.
2f780 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2f790 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20  n the templates 
2f7a0 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65  above, NNN repre
2f7b0 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72  sents an integer
2f7c0 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64   literal,.** and
2f7d0 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20   VVV represents 
2f7e0 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20  an alphanumeric 
2f7f0 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e  identifier.)^  ^
2f800 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68  The values of th
2f810 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ese.** parameter
2f820 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22  s (also called "
2f830 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
2f840 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61  ames" or "SQL pa
2f850 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61  rameters").** ca
2f860 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74  n be set using t
2f870 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2f880 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66  *() routines def
2f890 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a  ined here..**.**
2f8a0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
2f8b0 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
2f8c0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2f8d0 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a  tines is always.
2f8e0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
2f8f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
2f900 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  t] object return
2f910 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  ed from.** [sqli
2f920 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2f930 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
2f940 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  s..**.** ^The se
2f950 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2f960 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2f970 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  e SQL parameter 
2f980 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54  to be set..** ^T
2f990 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20  he leftmost SQL 
2f9a0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
2f9b0 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57   index of 1.  ^W
2f9c0 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  hen the same nam
2f9d0 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65  ed.** SQL parame
2f9e0 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65  ter is used more
2f9f0 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f   than once, seco
2fa00 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
2fa10 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73  t.** occurrences
2fa20 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69   have the same i
2fa30 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73  ndex as the firs
2fa40 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a  t occurrence..**
2fa50 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20   ^The index for 
2fa60 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73  named parameters
2fa70 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75   can be looked u
2fa80 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  p using the.** [
2fa90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2faa0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20  ameter_index()] 
2fab0 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20  API if desired. 
2fac0 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66   ^The index.** f
2fad0 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65  or "?NNN" parame
2fae0 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75  ters is the valu
2faf0 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68  e of NNN..** ^Th
2fb00 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74  e NNN value must
2fb10 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e   be between 1 an
2fb20 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  d the [sqlite3_l
2fb30 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d  imit()].** param
2fb40 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d  eter [SQLITE_LIM
2fb50 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
2fb60 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c  ER] (default val
2fb70 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20  ue: 999)..**.** 
2fb80 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
2fb90 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65  ent is the value
2fba0 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20   to bind to the 
2fbb0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
2fbc0 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
2fbd0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2fbe0 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20  _bind_text() or 
2fbf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2fc00 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  t16().** or sqli
2fc10 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
2fc20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2fc30 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  r then the fourt
2fc40 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  h parameter.** i
2fc50 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68  s ignored and th
2fc60 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20  e end result is 
2fc70 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69  the same as sqli
2fc80 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e  te3_bind_null().
2fc90 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
2fca0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
2fcb0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
2fcc0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
2fcd0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
2fce0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2fcf0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
2fd00 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
2fd10 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
2fd20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
2fd30 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
2fd40 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
2fd50 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2fd60 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
2fd70 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2fd80 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2fd90 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2fda0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2fdb0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
2fdc0 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68   then the length
2fdd0 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
2fde0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2fdf0 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
2fe00 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
2fe10 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20  rminator..** If 
2fe20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2fe30 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2fe40 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e  bind_blob() is n
2fe50 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a  egative, then.**
2fe60 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2fe70 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
2fe80 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  f a non-negative
2fe90 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2fea0 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f  r is provided to
2feb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2fec0 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  xt().** or sqlit
2fed0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2fee0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2fef0 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a  _text64() then.*
2ff00 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  * that parameter
2ff10 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
2ff20 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72  e offset.** wher
2ff30 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
2ff40 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72  ator would occur
2ff50 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74   assuming the st
2ff60 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a  ring were NUL.**
2ff70 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
2ff80 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
2ff90 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74  ers occur at byt
2ffa0 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74  e offsets less t
2ffb0 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75  han .** the valu
2ffc0 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  e of the fourth 
2ffd0 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74  parameter then t
2ffe0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
2fff0 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a  ing value will.*
30000 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  * contain embedd
30010 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65  ed NULs.  The re
30020 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
30030 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74  ons involving st
30040 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d  rings.** with em
30050 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
30060 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
30070 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
30080 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20  ent to the BLOB 
30090 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69  and string bindi
300a0 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  ng interfaces.**
300b0 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
300c0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
300d0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
300e0 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
300f0 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
30100 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54  hed with it.  ^T
30110 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
30120 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69   called.** to di
30130 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
30140 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e  B or string even
30150 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
30160 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a  bind API fails..
30170 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
30180 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
30190 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75  the special valu
301a0 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43  e [SQLITE_STATIC
301b0 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61  ], then SQLite a
301c0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
301d0 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
301e0 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d  s in static, unm
301f0 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64  anaged space and
30200 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
30210 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  o be freed..** ^
30220 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
30230 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61  ument has the va
30240 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e  lue [SQLITE_TRAN
30250 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20  SIENT], then.** 
30260 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73  SQLite makes its
30270 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
30280 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d  y of the data im
30290 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72  mediately, befor
302a0 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  e.** the sqlite3
302b0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
302c0 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  e returns..**.**
302d0 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67 75   ^The sixth argu
302e0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
302f0 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75  bind_text64() mu
30300 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  st be one of.** 
30310 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b  [SQLITE_UTF8], [
30320 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b  SQLITE_UTF16], [
30330 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
30340 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
30350 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69  6LE].** to speci
30360 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  fy the encoding 
30370 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20 74  of the text in t
30380 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
30390 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73  er.  If.** the s
303a0 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
303b0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
303c0 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e  xt64() is not on
303d0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f  e of the.** allo
303e0 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e  wed values shown
303f0 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68   above, or if th
30400 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
30410 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20  is different.** 
30420 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e  from the encodin
30430 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  g specified by t
30440 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65 74  he sixth paramet
30450 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  er, then the beh
30460 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65  avior.** is unde
30470 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
30480 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
30490 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
304a0 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
304b0 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
304c0 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
304d0 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65  h zeroes.  ^A ze
304e0 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
304f0 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
30500 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
30510 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
30520 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
30530 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
30540 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
30550 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
30560 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
30570 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
30580 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
30590 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
305a0 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
305b0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
305c0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
305d0 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
305e0 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  nes..** ^A negat
305f0 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
30600 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
30610 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
30620 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
30630 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73  ^If any of the s
30640 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
30650 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
30660 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
30670 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74  pointer.** for t
30680 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
30690 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20  tement] or with 
306a0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
306b0 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a  ment for which.*
306c0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
306d0 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
306e0 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79  ed more recently
306f0 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72   than [sqlite3_r
30700 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  eset()],.** then
30710 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72   the call will r
30720 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  eturn [SQLITE_MI
30730 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73  SUSE].  If any s
30740 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a  qlite3_bind_().*
30750 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73  * routine is pas
30760 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20  sed a [prepared 
30770 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
30780 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
30790 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ed, the.** resul
307a0 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  t is undefined a
307b0 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d  nd probably harm
307c0 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64  ful..**.** ^Bind
307d0 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
307e0 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
307f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
30800 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75  utine..** ^Unbou
30810 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
30820 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
30830 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
30840 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
30850 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
30860 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
30870 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a  success or an.**
30880 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
30890 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
308a0 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  rong..** ^[SQLIT
308b0 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20  E_TOOBIG] might 
308c0 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20 74  be returned if t
308d0 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72  he size of a str
308e0 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65  ing or BLOB.** e
308f0 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d  xceeds limits im
30900 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  posed by [sqlite
30910 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
30920 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20  _LIMIT_LENGTH]) 
30930 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  or.** [SQLITE_MA
30940 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b  X_LENGTH]..** ^[
30950 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73  SQLITE_RANGE] is
30960 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
30970 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e   parameter.** in
30980 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
30990 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e  nge.  ^[SQLITE_N
309a0 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65  OMEM] is returne
309b0 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61  d if malloc() fa
309c0 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ils..**.** See a
309d0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
309e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
309f0 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nt()],.** [sqlit
30a00 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
30a10 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b  r_name()], and [
30a20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
30a30 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
30a40 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
30a50 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
30a60 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
30a70 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
30a80 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
30a90 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
30aa0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
30ab0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34  ite3_bind_blob64
30ac0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30ad0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
30ae0 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  , sqlite3_uint64
30af0 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
30b00 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
30b10 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
30b20 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
30b30 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
30b40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30b50 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54  , double);.SQLIT
30b60 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
30b70 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
30b80 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
30b90 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
30ba0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
30bb0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
30bc0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
30bd0 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  e3_int64);.SQLIT
30be0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
30bf0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
30c00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
30c10 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
30c20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
30c30 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
30c40 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
30c50 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
30c60 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
30c70 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
30c80 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
30c90 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
30ca0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
30cb0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
30cc0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
30cd0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
30ce0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
30cf0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
30d00 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
30d10 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  4,.             
30d20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
30d30 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69  (*)(void*), unsi
30d40 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69  gned char encodi
30d50 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ng);.SQLITE_API 
30d60 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
30d70 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
30d80 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
30d90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
30da0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
30db0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
30dc0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
30dd0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
30de0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
30df0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
30e00 65 72 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  eroblob64(sqlite
30e10 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71  3_stmt*, int, sq
30e20 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a  lite3_uint64);..
30e30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30e40 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
30e50 72 61 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48  rameters.** METH
30e60 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
30e70 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
30e80 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
30e90 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
30ea0 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
30eb0 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
30ec0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30ed0 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
30ee0 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
30ef0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
30f00 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
30f10 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
30f20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
30f30 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
30f40 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
30f50 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
30f60 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
30f70 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
30f80 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
30f90 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
30fa0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
30fb0 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
30fc0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
30fd0 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
30fe0 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
30ff0 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
31000 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
31010 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
31020 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
31030 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
31040 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
31050 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
31060 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
31070 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
31080 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
31090 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
310a0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
310b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
310c0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
310d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
310e0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
310f0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
31100 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
31110 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
31120 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
31130 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
31140 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  er_count(sqlite3
31150 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
31160 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
31170 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74  f A Host Paramet
31180 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  er.** METHOD: sq
31190 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
311a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
311b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
311c0 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
311d0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
311e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
311f0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
31200 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
31210 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
31220 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
31230 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
31240 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
31250 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
31260 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
31270 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
31280 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
31290 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
312a0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
312b0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
312c0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
312d0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
312e0 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
312f0 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
31300 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
31310 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
31320 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
31330 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
31340 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
31350 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
31360 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
31370 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
31380 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
31390 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
313a0 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
313b0 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
313c0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
313d0 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
313e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
313f0 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
31400 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
31410 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
31420 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
31430 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
31440 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
31450 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
31460 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
31470 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
31480 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
31490 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
314a0 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
314b0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
314c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
314d0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
314e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
314f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
31500 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
31510 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
31520 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
31530 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
31540 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
31550 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
31560 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
31570 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
31580 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
31590 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
315a0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
315b0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
315c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
315d0 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
315e0 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
315f0 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48  ven Name.** METH
31600 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
31610 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
31620 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
31630 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
31640 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
31650 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
31660 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
31670 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
31680 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
31690 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
316a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
316b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
316c0 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
316d0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
316e0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
316f0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
31700 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
31710 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
31720 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
31730 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
31740 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
31750 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
31760 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
31770 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
31780 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
31790 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
317a0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
317b0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
317c0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
317d0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
317e0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
317f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
31800 65 72 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53  er_name()]..*/.S
31810 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
31820 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
31830 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74  eter_index(sqlit
31840 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20  e3_stmt*, const 
31850 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f  char *zName);../
31860 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
31870 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67  eset All Binding
31880 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20  s On A Prepared 
31890 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54  Statement.** MET
318a0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
318b0 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
318c0 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
318d0 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
318e0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
318f0 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
31900 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
31910 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
31920 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
31930 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
31940 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
31950 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
31960 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
31970 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49  to NULL..*/.SQLI
31980 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
31990 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
319a0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
319b0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
319c0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
319d0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
319e0 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** METHOD: 
319f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
31a00 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e  ** ^Return the n
31a10 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
31a20 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
31a30 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  et returned by t
31a40 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
31a50 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66 20  statement]. ^If 
31a60 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
31a70 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d 65 61  urns 0, that mea
31a80 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65 70  ns the .** [prep
31a90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31aa0 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74 61 20  returns no data 
31ab0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20  (for example an 
31ac0 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e 48  [UPDATE])..** ^H
31ad0 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62 65 63  owever, just bec
31ae0 61 75 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ause this routin
31af0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73 69  e returns a posi
31b00 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f 65 73  tive number does
31b10 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68 61   not.** mean tha
31b20 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72 6f  t one or more ro
31b30 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c 6c 20  ws of data will 
31b40 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 41  be returned.  ^A
31b50 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
31b60 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79 73  t.** will always
31b70 20 68 61 76 65 20 61 20 70 6f 73 69 74 69 76 65   have a positive
31b80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31b90 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65 70 65  count() but depe
31ba0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a 20  nding on the.** 
31bb0 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e  WHERE clause con
31bc0 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 65  straints and the
31bd0 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c 20   table content, 
31be0 69 74 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20  it might return 
31bf0 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20 53  no rows..**.** S
31c00 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
31c10 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a  3_data_count()].
31c20 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
31c30 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
31c40 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
31c50 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
31c60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
31c70 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
31c80 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
31c90 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
31ca0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
31cb0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
31cc0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
31cd0 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
31ce0 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
31cf0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
31d00 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
31d10 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
31d20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
31d30 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
31d40 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
31d50 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
31d60 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
31d70 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
31d80 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
31d90 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
31da0 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
31db0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
31dc0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
31dd0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
31de0 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
31df0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
31e00 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
31e10 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
31e20 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
31e30 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
31e40 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
31e50 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
31e60 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
31e70 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
31e80 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
31e90 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
31ea0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
31eb0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
31ec0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
31ed0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
31ee0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31ef0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
31f00 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
31f10 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
31f20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
31f30 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
31f40 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
31f50 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
31f60 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
31f70 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
31f80 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
31f90 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
31fa0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
31fb0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
31fc0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
31fd0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
31fe0 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
31ff0 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
32000 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
32010 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
32020 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
32030 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
32040 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
32050 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
32060 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
32070 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
32080 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
32090 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
320a0 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
320b0 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
320c0 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
320d0 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
320e0 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
320f0 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
32100 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
32110 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
32120 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
32130 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
32140 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
32150 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
32160 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ext..*/.SQLITE_A
32170 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
32180 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
32190 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
321a0 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45  , int N);.SQLITE
321b0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
321c0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
321d0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
321e0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
321f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
32200 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
32210 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
32220 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
32230 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
32240 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
32250 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
32260 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
32270 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
32280 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
32290 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
322a0 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
322b0 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
322c0 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
322d0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
322e0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
322f0 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
32300 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
32310 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
32320 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
32330 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
32340 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
32350 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
32360 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
32370 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
32380 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
32390 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
323a0 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
323b0 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
323c0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
323d0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
323e0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
323f0 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
32400 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
32410 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
32420 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
32430 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
32440 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
32450 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
32460 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
32470 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
32480 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
32490 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
324a0 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
324b0 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
324c0 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
324d0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
324e0 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
324f0 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
32500 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
32510 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
32520 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
32530 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
32540 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
32550 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
32560 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
32570 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
32580 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
32590 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
325a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
325b0 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
325c0 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
325d0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
325e0 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
325f0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
32600 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
32610 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
32620 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
32630 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
32640 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
32650 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
32660 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
32670 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
32680 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
32690 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
326a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
326b0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
326c0 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
326d0 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
326e0 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
326f0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
32700 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
32710 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
32720 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
32730 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
32740 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
32750 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
32760 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
32770 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
32780 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
32790 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
327a0 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
327b0 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
327c0 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
327d0 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
327e0 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
327f0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
32800 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
32810 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
32820 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
32830 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
32840 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
32850 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
32860 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
32870 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
32880 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
32890 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
328a0 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
328b0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
328c0 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
328d0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
328e0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
328f0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
32900 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
32910 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
32920 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
32930 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
32940 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
32950 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
32960 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
32970 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
32980 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
32990 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
329a0 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
329b0 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
329c0 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
329d0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
329e0 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
329f0 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
32a00 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
32a10 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
32a20 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
32a30 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
32a40 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
32a50 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
32a60 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
32a70 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
32a80 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
32a90 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
32aa0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
32ab0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
32ac0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
32ad0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
32ae0 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71  tabase_name16(sq
32af0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
32b00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
32b10 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
32b20 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
32b30 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
32b40 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.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 61 62  lite3_column_tab
32b70 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  le_name16(sqlite
32b80 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
32b90 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
32ba0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
32bb0 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
32bc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
32bd0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
32be0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
32bf0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
32c00 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
32c10 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
32c20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63  ** CAPI3REF: Dec
32c30 6c 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f  lared Datatype O
32c40 66 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  f A Query Result
32c50 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
32c60 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
32c70 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
32c80 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
32c90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
32ca0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
32cb0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
32cc0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
32cd0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
32ce0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
32cf0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
32d00 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
32d10 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
32d20 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
32d30 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
32d40 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
32d50 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
32d60 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
32d70 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
32d80 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
32d90 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
32da0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
32db0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
32dc0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
32dd0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
32de0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
32df0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
32e00 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
32e10 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
32e20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
32e30 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
32e40 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
32e50 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
32e60 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
32e70 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
32e80 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
32e90 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
32ea0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
32eb0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
32ec0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
32ed0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
32ee0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
32ef0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
32f00 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
32f10 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
32f20 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
32f30 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
32f40 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
32f50 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
32f60 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
32f70 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
32f80 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
32f90 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
32fa0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
32fb0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
32fc0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
32fd0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
32fe0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
32ff0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
33000 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
33010 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
33020 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
33030 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
33040 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
33050 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
33060 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
33070 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
33080 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
33090 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
330a0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
330b0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
330c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
330d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
330e0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
330f0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
33100 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
33110 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
33120 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
33130 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
33140 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
33150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
33160 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
33170 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
33180 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
33190 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
331a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
331b0 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
331c0 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
331d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
331e0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
331f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
33200 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
33210 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
33220 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
33230 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
33240 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33250 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
33260 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
33270 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
33280 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
33290 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
332a0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
332b0 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
332c0 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
332d0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
332e0 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
332f0 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
33300 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
33310 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
33320 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
33330 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
33340 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
33350 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
33360 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
33370 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
33380 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
33390 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
333a0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
333b0 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
333c0 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
333d0 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
333e0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
333f0 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
33400 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
33410 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
33420 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
33430 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
33440 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
33450 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
33460 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
33470 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
33480 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
33490 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
334a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
334b0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
334c0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
334d0 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
334e0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
334f0 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
33500 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
33510 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
33520 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
33530 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
33540 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
33550 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
33560 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
33570 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
33580 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
33590 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
335a0 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
335b0 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
335c0 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
335d0 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
335e0 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
335f0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
33600 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
33610 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
33620 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
33630 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
33640 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
33650 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
33660 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
33670 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
33680 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
33690 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
336a0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
336b0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
336c0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
336d0 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
336e0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
336f0 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
33700 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
33710 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
33720 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
33730 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
33740 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
33750 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
33760 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
33770 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
33780 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
33790 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
337a0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
337b0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
337c0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
337d0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
337e0 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
337f0 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
33800 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
33810 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
33820 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
33830 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
33840 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
33850 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
33860 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
33870 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
33880 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
33890 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
338a0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
338b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
338c0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
338d0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
338e0 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
338f0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
33900 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
33910 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
33920 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
33930 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
33940 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
33950 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
33960 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
33970 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
33980 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
33990 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
339a0 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
339b0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
339c0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
339d0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
339e0 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
339f0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
33a00 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
33a10 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
33a20 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
33a30 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
33a40 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
33a50 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
33a60 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
33a70 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
33a80 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
33a90 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
33aa0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
33ab0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
33ac0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
33ad0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
33ae0 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
33af0 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
33b00 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
33b10 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
33b20 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
33b30 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
33b40 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
33b50 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
33b60 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
33b70 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
33b80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
33b90 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
33ba0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
33bb0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
33bc0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
33bd0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
33be0 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
33bf0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
33c00 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
33c10 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
33c20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
33c30 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
33c40 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
33c50 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
33c60 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
33c70 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
33c80 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
33c90 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
33ca0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
33cb0 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
33cc0 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
33cd0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
33ce0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
33cf0 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
33d00 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
33d10 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
33d20 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
33d30 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
33d40 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
33d50 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
33d60 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
33d70 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
33d80 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
33d90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
33da0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
33db0 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
33dc0 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
33dd0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
33de0 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
33df0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
33e00 74 20 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e  t after [version
33e10 20 33 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74   3.6.23.1] ([dat
33e20 65 6f 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a  eof:3.6.23.1],.*
33e30 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
33e40 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e   began.** callin
33e50 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
33e60 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ()] automaticall
33e70 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
33e80 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a  stance rather.**
33e90 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
33ea0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
33eb0 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f    This is not co
33ec0 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61  nsidered a compa
33ed0 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61  tibility.** brea
33ee0 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70  k because any ap
33ef0 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65  plication that e
33f00 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20  ver receives an 
33f10 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72  SQLITE_MISUSE er
33f20 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e  ror.** is broken
33f30 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   by definition. 
33f40 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   The [SQLITE_OMI
33f50 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d  T_AUTORESET] com
33f60 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
33f70 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
33f80 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c  to restore the l
33f90 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a  egacy behavior..
33fa0 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
33fb0 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
33fc0 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
33fd0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
33fe0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
33ff0 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
34000 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
34010 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
34020 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
34030 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
34040 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
34050 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
34060 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
34070 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
34080 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
34090 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
340a0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
340b0 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
340c0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
340d0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
340e0 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
340f0 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
34100 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
34110 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
34120 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
34130 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
34140 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
34150 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
34160 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
34170 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
34180 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
34190 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
341a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
341b0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
341c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
341d0 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
341e0 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
341f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
34200 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
34210 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
34220 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
34230 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
34240 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
34250 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
34260 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
34270 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
34280 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
34290 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
342a0 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  mmended..*/.SQLI
342b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
342c0 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
342d0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
342e0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
342f0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
34300 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45  result set.** ME
34310 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
34320 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
34330 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
34340 28 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (P) interface re
34350 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
34360 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
34370 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f  he.** current ro
34380 77 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  w of the result 
34390 73 65 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64  set of [prepared
343a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
343b0 2a 20 5e 49 66 20 70 72 65 70 61 72 65 64 20 73  * ^If prepared s
343c0 74 61 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20  tatement P does 
343d0 6e 6f 74 20 68 61 76 65 20 72 65 73 75 6c 74 73  not have results
343e0 20 72 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e   ready to return
343f0 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74  .** (via calls t
34400 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
34410 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69  olumn_int | sqli
34420 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20  te3_column_*()] 
34430 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  of.** interfaces
34440 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64  ) then sqlite3_d
34450 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74  ata_count(P) ret
34460 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  urns 0..** ^The 
34470 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
34480 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c  nt(P) routine al
34490 73 6f 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  so returns 0 if 
344a0 50 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  P is a NULL poin
344b0 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ter..** ^The sql
344c0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
344d0 50 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  P) routine retur
344e0 6e 73 20 30 20 69 66 20 74 68 65 20 70 72 65 76  ns 0 if the prev
344f0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  ious call to.** 
34500 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
34510 29 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  ) returned [SQLI
34520 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20  TE_DONE].  ^The 
34530 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
34540 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  nt(P).** will re
34550 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66  turn non-zero if
34560 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
34570 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d  o [sqlite3_step]
34580 28 50 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  (P) returned.** 
34590 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78  [SQLITE_ROW], ex
345a0 63 65 70 74 20 69 6e 20 74 68 65 20 63 61 73 65  cept in the case
345b0 20 6f 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20   of the [PRAGMA 
345c0 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75  incremental_vacu
345d0 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20  um].** where it 
345e0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a  always returns z
345f0 65 72 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73  ero since each s
34600 74 65 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74  tep of that mult
34610 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61  i-step.** pragma
34620 20 72 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d   returns 0 colum
34630 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ns of data..**.*
34640 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
34650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
34660 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  t()].*/.SQLITE_A
34670 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  PI int sqlite3_d
34680 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
34690 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
346a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
346b0 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
346c0 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
346d0 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
346e0 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
346f0 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
34700 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
34710 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
34720 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
34730 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
34740 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
34750 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
34760 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
34770 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
34780 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
34790 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
347a0 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
347b0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
347c0 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
347d0 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
347e0 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
347f0 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
34800 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
34810 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
34820 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
34830 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
34840 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
34850 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
34860 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
34870 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
34880 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
34890 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
348a0 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
348b0 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
348c0 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
348d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
348e0 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
348f0 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
34900 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
34910 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
34920 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
34930 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
34940 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
34950 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
34960 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
34970 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
34980 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
34990 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
349a0 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
349b0 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
349c0 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
349d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
349e0 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
349f0 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
34a00 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
34a10 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
34a20 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f  ines return info
34a30 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20  rmation about a 
34a40 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66  single column of
34a50 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
34a60 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20  result row of a 
34a70 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72  query.  ^In ever
34a80 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73 74  y case the first
34a90 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
34aa0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
34ab0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
34ac0 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65  ment] that is be
34ad0 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28 74  ing evaluated (t
34ae0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
34af0 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72  *].** that was r
34b00 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71  eturned from [sq
34b10 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
34b20 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74  ()] or one of it
34b30 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61  s variants).** a
34b40 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  nd the second ar
34b50 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
34b60 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  dex of the colum
34b70 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f  n for which info
34b80 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  rmation.** shoul
34b90 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e  d be returned. ^
34ba0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
34bb0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
34bc0 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69 6e  t set has the in
34bd0 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e  dex 0..** ^The n
34be0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
34bf0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63   in the result c
34c00 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
34c10 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
34c20 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
34c30 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  )]..**.** If the
34c40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64   SQL statement d
34c50 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c  oes not currentl
34c60 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c  y point to a val
34c70 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68  id row, or if th
34c80 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65  e.** column inde
34c90 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
34ca0 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  e, the result is
34cb0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
34cc0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61  hese routines ma
34cd0 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  y only be called
34ce0 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72   when the most r
34cf0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a  ecent call to.**
34d00 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
34d10 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b  ] has returned [
34d20 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20  SQLITE_ROW] and 
34d30 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69  neither.** [sqli
34d40 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72  te3_reset()] nor
34d50 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
34d60 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20  ze()] have been 
34d70 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e  called subsequen
34d80 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f  tly..** If any o
34d90 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
34da0 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65   are called afte
34db0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
34dc0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
34dd0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
34de0 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  r after [sqlite3
34df0 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
34e00 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69  urned.** somethi
34e10 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ng other than [S
34e20 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20  QLITE_ROW], the 
34e30 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
34e40 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71  fined..** If [sq
34e50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
34e60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
34e70 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
34e80 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72  inalize()].** ar
34e90 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20  e called from a 
34ea0 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
34eb0 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68   while any of th
34ec0 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  ese routines.** 
34ed0 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65  are pending, the
34ee0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
34ef0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  e undefined..**.
34f00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34f10 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f  column_type() ro
34f20 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
34f30 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e.** [SQLITE_INT
34f40 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 20  EGER | datatype 
34f50 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e  code] for the in
34f60 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a  itial data type.
34f70 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
34f80 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72   column.  ^The r
34f90 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73  eturned value is
34fa0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
34fb0 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51  INTEGER],.** [SQ
34fc0 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51  LITE_FLOAT], [SQ
34fd0 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c  LITE_TEXT], [SQL
34fe0 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53  ITE_BLOB], or [S
34ff0 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68  QLITE_NULL].  Th
35000 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
35010 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
35020 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
35030 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20  only meaningful 
35040 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f  if no type.** co
35050 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f  nversions have o
35060 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63 72  ccurred as descr
35070 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74  ibed below.  Aft
35080 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  er a type conver
35090 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c  sion,.** the val
350a0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ue returned by s
350b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
350c0 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  pe() is undefine
350d0 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65  d.  Future.** ve
350e0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
350f0 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65 20   may change the 
35100 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
35110 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
35120 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  ).** following a
35130 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
35140 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
35150 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
35160 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67   or UTF-8 string
35170 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
35180 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
35190 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
351a0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
351b0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
351c0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
351d0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
351e0 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73 74  t is a UTF-16 st
351f0 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
35200 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
35210 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
35220 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
35230 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  8 and then retur
35240 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
35250 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
35260 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
35270 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
35280 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
35290 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a  _bytes() uses.**
352a0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
352b0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
352c0 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
352d0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e   UTF-8 string an
352e0 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  d returns.** the
352f0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
35300 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e   in that string.
35310 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
35320 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  lt is NULL, then
35330 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35340 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73 20  bytes() returns 
35350 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  zero..**.** ^If 
35360 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
35370 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73  BLOB or UTF-16 s
35380 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
35390 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
353a0 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  tes16().** routi
353b0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
353c0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
353d0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
353e0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
353f0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
35400 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  F-8 string, then
35410 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35420 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72  bytes16() conver
35430 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
35440 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74   to UTF-16 and t
35450 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
35460 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
35470 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
35480 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
35490 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
354a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
354b0 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  6() uses.** [sql
354c0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
354d0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
354e0 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
354f0 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  16 string and re
35500 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
35510 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
35520 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
35530 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
35540 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
35550 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35560 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65  s16() returns ze
35570 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76  ro..**.** ^The v
35580 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
35590 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
355a0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a  n_bytes()] and .
355b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
355c0 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f  mn_bytes16()] do
355d0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65   not include the
355e0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
355f0 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20  s at the end.** 
35600 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20  of the string.  
35610 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68  ^For clarity: th
35620 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
35630 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
35640 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
35650 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
35660 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
35670 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  are the number o
35680 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68  f.** bytes in th
35690 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68  e string, not th
356a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
356b0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53  acters..**.** ^S
356c0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
356d0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
356e0 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c  n_text() and sql
356f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35700 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d  16(),.** even em
35710 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65  pty strings, are
35720 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72   always zero-ter
35730 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72  minated.  ^The r
35740 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66  eturn.** value f
35750 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  rom sqlite3_colu
35760 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20  mn_blob() for a 
35770 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
35780 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
35790 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72  er..**.** <b>War
357a0 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f  ning:</b> ^The o
357b0 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
357c0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
357d0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e  n_value()] is an
357e0 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
357f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
35800 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75  object.  In a mu
35810 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e 76 69  ltithreaded envi
35820 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75  ronment,.** an u
35830 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
35840 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
35850 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
35860 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20   safely with.** 
35870 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
35880 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
35890 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
358a0 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
358b0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
358c0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
358d0 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
358e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
358f0 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
35900 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
35910 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
35920 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
35930 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
35940 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
35950 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
35960 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
35970 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
35980 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69  s()], the behavi
35990 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  or is not thread
359a0 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  safe..**.** Thes
359b0 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
359c0 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
359d0 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
359e0 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
359f0 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
35a00 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
35a10 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
35a20 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
35a30 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
35a40 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
35a50 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
35a60 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
35a70 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
35a80 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
35a90 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
35aa0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
35ab0 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
35ac0 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
35ad0 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
35ae0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
35af0 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
35b00 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
35b10 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
35b20 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
35b30 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
35b40 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
35b50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
35b60 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
35b70 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
35b80 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
35b90 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
35ba0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
35bb0 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
35bc0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
35bd0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
35be0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
35bf0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
35c00 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
35c10 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
35c20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
35c30 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
35c40 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
35c50 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
35c60 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
35c70 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
35c80 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
35c90 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
35ca0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
35cb0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
35cc0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
35cd0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
35ce0 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
35cf0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
35d00 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
35d10 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
35d20 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
35d30 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
35d40 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
35d50 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
35d60 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
35d70 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
35d80 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
35d90 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
35da0 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
35db0 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
35dc0 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c  to BLOB.** <tr><
35dd0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
35de0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
35df0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
35e00 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
35e10 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
35e20 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
35e30 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
35e40 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
35e50 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
35e60 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
35e70 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
35e80 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
35e90 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
35ea0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
35eb0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
35ec0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
35ed0 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
35ee0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
35ef0 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
35f00 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
35f10 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
35f20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
35f30 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
35f40 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e  quote>)^.**.** N
35f50 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
35f60 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
35f70 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
35f80 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
35f90 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
35fa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
35fb0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
35fc0 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
35fd0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
35fe0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
35ff0 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
36000 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
36010 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
36020 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
36030 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
36040 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
36050 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
36060 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
36070 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
36080 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
36090 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
360a0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
360b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
360c0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
360d0 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
360e0 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
360f0 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
36100 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
36110 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
36120 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
36130 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
36140 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
36150 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
36160 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
36170 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
36180 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
36190 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
361a0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
361b0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
361c0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
361d0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
361e0 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
361f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36200 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
36210 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
36220 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
36230 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
36240 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
36250 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
36260 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
36270 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  >.**.** ^Convers
36280 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
36290 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
362a0 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
362b0 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
362c0 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
362d0 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
362e0 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
362f0 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
36300 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
36310 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
36320 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72  or pointer refer
36330 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20  ences will have 
36340 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
36350 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
36360 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
36370 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
36380 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
36390 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
363a0 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
363b0 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
363c0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
363d0 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
363e0 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
363f0 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 70  .** The safest p
36400 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f  olicy is to invo
36410 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ke these routine
36420 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74  s.** in one of t
36430 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79  he following way
36440 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
36450 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
36460 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c  lumn_text() foll
36470 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
36480 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
36490 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
364a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
364b0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
364c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
364d0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
364e0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
364f0 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77  _text16() follow
36500 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
36510 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f  lumn_bytes16()</
36520 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  li>.** </ul>.**.
36530 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
36540 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61  s, you should ca
36550 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ll sqlite3_colum
36560 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c  n_text(),.** sql
36570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
36580 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  (), or sqlite3_c
36590 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
365a0 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68  irst to force th
365b0 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f  e result.** into
365c0 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72   the desired for
365d0 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65  mat, then invoke
365e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
365f0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71  bytes() or.** sq
36600 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
36610 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74  es16() to find t
36620 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72  he size of the r
36630 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d  esult.  Do not m
36640 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73  ix calls.** to s
36650 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36660 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
36670 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69  column_blob() wi
36680 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  th calls to.** s
36690 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
366a0 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20  tes16(), and do 
366b0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f  not mix calls to
366c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
366d0 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68  text16().** with
366e0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
366f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
36700 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69  ..**.** ^The poi
36710 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61  nters returned a
36720 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61  re valid until a
36730 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
36740 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65   occurs as.** de
36750 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f  scribed above, o
36760 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33  r until [sqlite3
36770 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
36780 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
36790 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
367a0 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c  alize()] is call
367b0 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79  ed.  ^The memory
367c0 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68   space used to h
367d0 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61  old strings.** a
367e0 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65  nd BLOBs is free
367f0 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  d automatically.
36800 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d    Do <em>not</em
36810 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74  > pass the point
36820 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ers returned.** 
36830 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
36840 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  lumn_blob()], [s
36850 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36860 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f  xt()], etc. into
36870 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
36880 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  e()]..**.** ^(If
36890 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
368a0 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  tion error occur
368b0 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61  s during the eva
368c0 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a  luation of any.*
368d0 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  * of these routi
368e0 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76  nes, a default v
368f0 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64  alue is returned
36900 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  .  The default v
36910 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65  alue.** is eithe
36920 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c  r the integer 0,
36930 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f   the floating po
36940 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20  int number 0.0, 
36950 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  or a NULL.** poi
36960 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e  nter.  Subsequen
36970 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
36980 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77  te3_errcode()] w
36990 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53  ill return.** [S
369a0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a  QLITE_NOMEM].)^.
369b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
369c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
369d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71  3_column_blob(sq
369e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
369f0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
36a00 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
36a10 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
36a20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36a30 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
36a40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
36a50 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
36a60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36a70 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
36a80 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
36a90 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71  column_double(sq
36aa0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
36ab0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
36ac0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
36ad0 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65  olumn_int(sqlite
36ae0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
36af0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  l);.SQLITE_API s
36b00 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
36b10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
36b20 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
36b30 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
36b40 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73  TE_API const uns
36b50 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
36b60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
36b70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36b80 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
36b90 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
36ba0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
36bb0 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
36bc0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
36bd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
36be0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36bf0 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
36c00 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
36c10 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
36c20 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
36c30 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
36c40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36c50 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
36c60 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
36c70 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
36c80 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44  ment Object.** D
36c90 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  ESTRUCTOR: sqlit
36ca0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
36cb0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
36cc0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
36cd0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
36ce0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
36cf0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
36d00 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
36d10 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
36d20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
36d30 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
36d40 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
36d50 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
36d60 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
36d70 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
36d80 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
36d90 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
36da0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
36db0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
36dc0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
36dd0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
36de0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
36df0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
36e00 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
36e10 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
36e20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
36e30 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
36e40 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
36e50 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
36e60 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
36e70 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
36e80 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
36e90 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
36ea0 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
36eb0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
36ec0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
36ed0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
36ee0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
36ef0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
36f00 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
36f10 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
36f20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
36f30 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
36f40 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
36f50 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
36f60 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
36f70 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
36f80 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
36f90 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
36fa0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
36fb0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
36fc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
36fd0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
36fe0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
36ff0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
37000 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
37010 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
37020 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
37030 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
37040 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37050 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
37060 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
37070 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
37080 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
37090 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
370a0 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
370b0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
370c0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
370d0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
370e0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
370f0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
37100 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
37110 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
37120 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
37130 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
37140 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
37150 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
37160 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
37170 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
37180 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
37190 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45  ent Object.** ME
371a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
371b0 6d 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  mt.**.** The sql
371c0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
371d0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
371e0 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
371f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
37200 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
37210 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
37220 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
37230 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
37240 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
37250 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
37260 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
37270 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
37280 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
37290 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
372a0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
372b0 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
372c0 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
372d0 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
372e0 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
372f0 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
37300 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
37310 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
37320 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
37330 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
37340 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
37350 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
37360 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
37370 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
37380 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
37390 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
373a0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
373b0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
373c0 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
373d0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
373e0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
373f0 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
37400 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
37410 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
37420 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
37430 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
37440 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
37450 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
37460 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
37470 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
37480 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
37490 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
374a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
374b0 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
374c0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
374d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
374e0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
374f0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
37500 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
37510 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
37520 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
37530 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
37540 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
37550 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
37560 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
37570 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
37580 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
37590 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50   S..*/.SQLITE_AP
375a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  I int sqlite3_re
375b0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
375c0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
375d0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
375e0 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
375f0 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
37600 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
37610 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
37620 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
37630 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
37640 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
37650 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
37660 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
37670 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
37680 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44  tions}.** METHOD
37690 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
376a0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
376b0 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
376c0 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
376d0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
376e0 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
376f0 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
37700 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
37710 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
37720 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
37730 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
37740 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
37750 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
37760 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
37770 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
37780 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
37790 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
377a0 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
377b0 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
377c0 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
377d0 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
377e0 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
377f0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
37800 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
37810 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
37820 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
37830 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
37840 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
37850 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
37860 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
37870 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37880 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
37890 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
378a0 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
378b0 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
378c0 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
378d0 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
378e0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
378f0 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
37900 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
37910 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
37920 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
37930 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
37940 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
37950 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
37960 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
37970 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
37980 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
37990 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
379a0 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
379b0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
379c0 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
379d0 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
379e0 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
379f0 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
37a00 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
37a10 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
37a20 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
37a30 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
37a40 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
37a50 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
37a60 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
37a70 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
37a80 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
37a90 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
37aa0 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
37ab0 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
37ac0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
37ad0 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
37ae0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
37af0 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
37b00 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
37b10 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
37b20 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
37b30 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
37b40 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
37b50 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
37b60 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
37b70 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
37b80 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
37b90 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
37ba0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
37bb0 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
37bc0 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
37bd0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
37be0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
37bf0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
37c00 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
37c10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
37c20 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
37c30 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
37c40 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
37c50 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
37c60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
37c70 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
37c80 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
37c90 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
37ca0 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
37cb0 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
37cc0 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
37cd0 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
37ce0 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61  rameters.  The a
37cf0 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
37d00 64 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d  d set this param
37d10 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49  eter to.** [SQLI
37d20 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74  TE_UTF16LE] if t
37d30 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  he function impl
37d40 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
37d50 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  es .** [sqlite3_
37d60 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29  value_text16le()
37d70 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f  ] on an input, o
37d80 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  r [SQLITE_UTF16B
37d90 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70  E] if the.** imp
37da0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f  lementation invo
37db0 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  kes [sqlite3_val
37dc0 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f  ue_text16be()] o
37dd0 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a  n an input, or.*
37de0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  * [SQLITE_UTF16]
37df0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   if [sqlite3_val
37e00 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20  ue_text16()] is 
37e10 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  used, or [SQLITE
37e20 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77  _UTF8].** otherw
37e30 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20  ise.  ^The same 
37e40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  SQL function may
37e50 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d   be registered m
37e60 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73  ultiple times us
37e70 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74  ing.** different
37e80 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
37e90 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20  encodings, with 
37ea0 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d  different implem
37eb0 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a  entations for.**
37ec0 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a   each encoding..
37ed0 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c  ** ^When multipl
37ee0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
37ef0 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75  s of the same fu
37f00 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c  nction are avail
37f10 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  able, SQLite.** 
37f20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e  will pick the on
37f30 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20  e that involves 
37f40 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
37f50 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73   of data convers
37f60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
37f70 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
37f80 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   may optionally 
37f90 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51  be ORed with [SQ
37fa0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
37fb0 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  IC].** to signal
37fc0 20 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69   that the functi
37fd0 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72  on will always r
37fe0 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72  eturn the same r
37ff0 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74  esult given.** t
38000 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77  he same inputs w
38010 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53  ithin a single S
38020 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d  QL statement.  M
38030 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ost SQL function
38040 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69  s are.** determi
38050 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69  nistic.  The bui
38060 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d  lt-in [random()]
38070 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
38080 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61   an example of a
38090 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  .** function tha
380a0 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69  t is not determi
380b0 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c  nistic.  The SQL
380c0 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65  ite query planne
380d0 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20  r is able to.** 
380e0 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e  perform addition
380f0 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  al optimizations
38100 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69   on deterministi
38110 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20  c functions, so 
38120 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  use.** of the [S
38130 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
38140 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63  TIC] flag is rec
38150 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70  ommended where p
38160 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ossible..**.** ^
38170 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
38180 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
38190 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
381a0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
381b0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
381c0 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
381d0 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
381e0 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
381f0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
38200 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
38210 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
38220 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
38230 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
38240 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
38250 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
38260 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
38270 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
38280 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
38290 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
382a0 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
382b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
382c0 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
382d0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
382e0 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
382f0 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
38300 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
38310 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
38320 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
38330 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
38340 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
38350 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
38360 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
38370 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
38380 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
38390 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
383a0 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
383b0 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
383c0 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
383d0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
383e0 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
383f0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20  LL pointers for 
38400 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
38410 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
38420 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
38430 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  ninth parameter 
38440 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
38450 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
38460 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
38470 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
38480 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
38490 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
384a0 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
384b0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
384c0 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
384d0 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
384e0 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
384f0 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
38500 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
38510 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38520 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
38530 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
38540 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
38550 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
38560 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
38570 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
38580 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
38590 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
385a0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
385b0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
385c0 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
385d0 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
385e0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
385f0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
38600 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
38610 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
38620 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
38630 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
38640 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
38650 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
38660 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
38670 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
38680 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
38690 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
386a0 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
386b0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
386c0 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
386d0 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
386e0 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
386f0 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
38700 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
38710 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
38720 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
38730 0a 2a 2a 20 74 68 65 20 69