System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact bcc4a1989db45e7f223191f2d0f66c1c28946383:


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 34 2e 32 2e 20 20  ersion 3.14.2.  
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 57 68 61 74  .#endif../* What
1eb0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 47 43 43 20   version of GCC 
1ec0: 69 73 20 62 65 69 6e 67 20 75 73 65 64 2e 20 20  is being used.  
1ed0: 30 20 6d 65 61 6e 73 20 47 43 43 20 69 73 20 6e  0 means GCC is n
1ee0: 6f 74 20 62 65 69 6e 67 20 75 73 65 64 20 2a 2f  ot being used */
1ef0: 0a 23 69 66 64 65 66 20 5f 5f 47 4e 55 43 5f 5f  .#ifdef __GNUC__
1f00: 0a 23 20 64 65 66 69 6e 65 20 47 43 43 5f 56 45  .# define GCC_VE
1f10: 52 53 49 4f 4e 20 28 5f 5f 47 4e 55 43 5f 5f 2a  RSION (__GNUC__*
1f20: 31 30 30 30 30 30 30 2b 5f 5f 47 4e 55 43 5f 4d  1000000+__GNUC_M
1f30: 49 4e 4f 52 5f 5f 2a 31 30 30 30 2b 5f 5f 47 4e  INOR__*1000+__GN
1f40: 55 43 5f 50 41 54 43 48 4c 45 56 45 4c 5f 5f 29  UC_PATCHLEVEL__)
1f50: 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
1f60: 47 43 43 5f 56 45 52 53 49 4f 4e 20 30 0a 23 65  GCC_VERSION 0.#e
1f70: 6e 64 69 66 0a 0a 2f 2a 20 4e 65 65 64 65 64 20  ndif../* Needed 
1f80: 66 6f 72 20 76 61 72 69 6f 75 73 20 64 65 66 69  for various defi
1f90: 6e 69 74 69 6f 6e 73 2e 2e 2e 20 2a 2f 0a 23 69  nitions... */.#i
1fa0: 66 20 64 65 66 69 6e 65 64 28 5f 5f 47 4e 55 43  f defined(__GNUC
1fb0: 5f 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64 28  __) && !defined(
1fc0: 5f 47 4e 55 5f 53 4f 55 52 43 45 29 0a 23 20 64  _GNU_SOURCE).# d
1fd0: 65 66 69 6e 65 20 5f 47 4e 55 5f 53 4f 55 52 43  efine _GNU_SOURC
1fe0: 45 0a 23 65 6e 64 69 66 0a 0a 23 69 66 20 64 65  E.#endif..#if de
1ff0: 66 69 6e 65 64 28 5f 5f 4f 70 65 6e 42 53 44 5f  fined(__OpenBSD_
2000: 5f 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f  _) && !defined(_
2010: 42 53 44 5f 53 4f 55 52 43 45 29 0a 23 20 64 65  BSD_SOURCE).# de
2020: 66 69 6e 65 20 5f 42 53 44 5f 53 4f 55 52 43 45  fine _BSD_SOURCE
2030: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 46  .#endif../*.** F
2040: 6f 72 20 4d 69 6e 47 57 2c 20 63 68 65 63 6b 20  or MinGW, check 
2050: 74 6f 20 73 65 65 20 69 66 20 77 65 20 63 61 6e  to see if we can
2060: 20 69 6e 63 6c 75 64 65 20 74 68 65 20 68 65 61   include the hea
2070: 64 65 72 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e  der file contain
2080: 69 6e 67 20 69 74 73 0a 2a 2a 20 76 65 72 73 69  ing its.** versi
2090: 6f 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2c 20  on information, 
20a0: 61 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e  among other thin
20b0: 67 73 2e 20 20 4e 6f 72 6d 61 6c 6c 79 2c 20 74  gs.  Normally, t
20c0: 68 69 73 20 69 6e 74 65 72 6e 61 6c 20 4d 69 6e  his internal Min
20d0: 47 57 0a 2a 2a 20 68 65 61 64 65 72 20 66 69 6c  GW.** header fil
20e0: 65 20 77 6f 75 6c 64 20 5b 6f 6e 6c 79 5d 20 62  e would [only] b
20f0: 65 20 69 6e 63 6c 75 64 65 64 20 61 75 74 6f 6d  e included autom
2100: 61 74 69 63 61 6c 6c 79 20 62 79 20 6f 74 68 65  atically by othe
2110: 72 20 4d 69 6e 47 57 20 68 65 61 64 65 72 0a 2a  r MinGW header.*
2120: 2a 20 66 69 6c 65 73 3b 20 68 6f 77 65 76 65 72  * files; however
2130: 2c 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 64 20  , the contained 
2140: 76 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d 61 74  version informat
2150: 69 6f 6e 20 69 73 20 6e 6f 77 20 72 65 71 75 69  ion is now requi
2160: 72 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 68  red by this.** h
2170: 65 61 64 65 72 20 66 69 6c 65 20 74 6f 20 77 6f  eader file to wo
2180: 72 6b 20 61 72 6f 75 6e 64 20 62 69 6e 61 72 79  rk around binary
2190: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 69   compatibility i
21a0: 73 73 75 65 73 20 28 73 65 65 20 62 65 6c 6f 77  ssues (see below
21b0: 29 20 61 6e 64 0a 2a 2a 20 74 68 69 73 20 69 73  ) and.** this is
21c0: 20 74 68 65 20 6f 6e 6c 79 20 6b 6e 6f 77 6e 20   the only known 
21d0: 77 61 79 20 74 6f 20 72 65 6c 69 61 62 6c 79 20  way to reliably 
21e0: 6f 62 74 61 69 6e 20 69 74 2e 20 20 54 68 69 73  obtain it.  This
21f0: 20 65 6e 74 69 72 65 20 23 69 66 20 62 6c 6f 63   entire #if bloc
2200: 6b 0a 2a 2a 20 77 6f 75 6c 64 20 62 65 20 63 6f  k.** would be co
2210: 6d 70 6c 65 74 65 6c 79 20 75 6e 6e 65 63 65 73  mpletely unneces
2220: 73 61 72 79 20 69 66 20 74 68 65 72 65 20 77 61  sary if there wa
2230: 73 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 20  s any other way 
2240: 6f 66 20 64 65 74 65 63 74 69 6e 67 0a 2a 2a 20  of detecting.** 
2250: 4d 69 6e 47 57 20 76 69 61 20 74 68 65 69 72 20  MinGW via their 
2260: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 28 65 2e  preprocessor (e.
2270: 67 2e 20 69 66 20 74 68 65 79 20 63 75 73 74 6f  g. if they custo
2280: 6d 69 7a 65 64 20 74 68 65 69 72 20 47 43 43 20  mized their GCC 
2290: 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 73 6f 6d  to define.** som
22a0: 65 20 4d 69 6e 47 57 2d 73 70 65 63 69 66 69 63  e MinGW-specific
22b0: 20 6d 61 63 72 6f 73 29 2e 20 20 57 68 65 6e 20   macros).  When 
22c0: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 4d 69  compiling for Mi
22d0: 6e 47 57 2c 20 65 69 74 68 65 72 20 74 68 65 0a  nGW, either the.
22e0: 2a 2a 20 5f 48 41 56 45 5f 4d 49 4e 47 57 5f 48  ** _HAVE_MINGW_H
22f0: 20 6f 72 20 5f 48 41 56 45 5f 5f 4d 49 4e 47 57   or _HAVE__MINGW
2300: 5f 48 20 28 6e 6f 74 65 20 74 68 65 20 65 78 74  _H (note the ext
2310: 72 61 20 75 6e 64 65 72 73 63 6f 72 65 29 20 6d  ra underscore) m
2320: 61 63 72 6f 20 6d 75 73 74 20 62 65 0a 2a 2a 20  acro must be.** 
2330: 64 65 66 69 6e 65 64 3b 20 6f 74 68 65 72 77 69  defined; otherwi
2340: 73 65 2c 20 64 65 74 65 63 74 69 6f 6e 20 6f 66  se, detection of
2350: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 73 70 65 63   conditions spec
2360: 69 66 69 63 20 74 6f 20 4d 69 6e 47 57 20 77 69  ific to MinGW wi
2370: 6c 6c 20 62 65 0a 2a 2a 20 64 69 73 61 62 6c 65  ll be.** disable
2380: 64 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  d..*/.#if define
2390: 64 28 5f 48 41 56 45 5f 4d 49 4e 47 57 5f 48 29  d(_HAVE_MINGW_H)
23a0: 0a 23 20 69 6e 63 6c 75 64 65 20 22 6d 69 6e 67  .# include "ming
23b0: 77 2e 68 22 0a 23 65 6c 69 66 20 64 65 66 69 6e  w.h".#elif defin
23c0: 65 64 28 5f 48 41 56 45 5f 5f 4d 49 4e 47 57 5f  ed(_HAVE__MINGW_
23d0: 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 22 5f 6d  H).# include "_m
23e0: 69 6e 67 77 2e 68 22 0a 23 65 6e 64 69 66 0a 0a  ingw.h".#endif..
23f0: 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47 57 20  /*.** For MinGW 
2400: 76 65 72 73 69 6f 6e 20 34 2e 78 20 28 61 6e 64  version 4.x (and
2410: 20 68 69 67 68 65 72 29 2c 20 63 68 65 63 6b 20   higher), check 
2420: 74 6f 20 73 65 65 20 69 66 20 74 68 65 20 5f 55  to see if the _U
2430: 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f 54 0a  SE_32BIT_TIME_T.
2440: 2a 2a 20 64 65 66 69 6e 65 20 69 73 20 72 65 71  ** define is req
2450: 75 69 72 65 64 20 74 6f 20 6d 61 69 6e 74 61 69  uired to maintai
2460: 6e 20 62 69 6e 61 72 79 20 63 6f 6d 70 61 74 69  n binary compati
2470: 62 69 6c 69 74 79 20 77 69 74 68 20 74 68 65 20  bility with the 
2480: 4d 53 56 43 20 72 75 6e 74 69 6d 65 0a 2a 2a 20  MSVC runtime.** 
2490: 6c 69 62 72 61 72 79 20 69 6e 20 75 73 65 20 28  library in use (
24a0: 65 2e 67 2e 20 66 6f 72 20 57 69 6e 64 6f 77 73  e.g. for Windows
24b0: 20 58 50 29 2e 0a 2a 2f 0a 23 69 66 20 21 64 65   XP)..*/.#if !de
24c0: 66 69 6e 65 64 28 5f 55 53 45 5f 33 32 42 49 54  fined(_USE_32BIT
24d0: 5f 54 49 4d 45 5f 54 29 20 26 26 20 21 64 65 66  _TIME_T) && !def
24e0: 69 6e 65 64 28 5f 55 53 45 5f 36 34 42 49 54 5f  ined(_USE_64BIT_
24f0: 54 49 4d 45 5f 54 29 20 26 26 20 5c 0a 20 20 20  TIME_T) && \.   
2500: 20 64 65 66 69 6e 65 64 28 5f 57 49 4e 33 32 29   defined(_WIN32)
2510: 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 57 49   && !defined(_WI
2520: 4e 36 34 29 20 26 26 20 5c 0a 20 20 20 20 64 65  N64) && \.    de
2530: 66 69 6e 65 64 28 5f 5f 4d 49 4e 47 57 5f 4d 41  fined(__MINGW_MA
2540: 4a 4f 52 5f 56 45 52 53 49 4f 4e 29 20 26 26 20  JOR_VERSION) && 
2550: 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f 52 5f 56 45  __MINGW_MAJOR_VE
2560: 52 53 49 4f 4e 20 3e 3d 20 34 20 26 26 20 5c 0a  RSION >= 4 && \.
2570: 20 20 20 20 64 65 66 69 6e 65 64 28 5f 5f 4d 53      defined(__MS
2580: 56 43 52 54 5f 5f 29 0a 23 20 64 65 66 69 6e 65  VCRT__).# define
2590: 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45   _USE_32BIT_TIME
25a0: 5f 54 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 54 68  _T.#endif../* Th
25b0: 65 20 70 75 62 6c 69 63 20 53 51 4c 69 74 65 20  e public SQLite 
25c0: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
25d0: 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54  _FILE_OFFSET_BIT
25e0: 53 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70 70  S macro must app
25f0: 65 61 72 0a 2a 2a 20 66 69 72 73 74 20 69 6e 20  ear.** first in 
2600: 51 4e 58 2e 20 20 41 6c 73 6f 2c 20 74 68 65 20  QNX.  Also, the 
2610: 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f  _USE_32BIT_TIME_
2620: 54 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70 70  T macro must app
2630: 65 61 72 20 66 69 72 73 74 20 66 6f 72 0a 2a 2a  ear first for.**
2640: 20 4d 69 6e 47 57 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a   MinGW..*/./****
2650: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75  ********** Inclu
2660: 64 65 20 73 71 6c 69 74 65 33 2e 68 20 69 6e 20  de sqlite3.h in 
2670: 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71  the middle of sq
2680: 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a  liteInt.h ******
2690: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a  *********/./****
26a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e  ********** Begin
26b0: 20 66 69 6c 65 20 73 71 6c 69 74 65 33 2e 68 20   file sqlite3.h 
26c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
26d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
26e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a  *********/./*.**
26f0: 20 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20   2001 September 
2700: 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  15.**.** The aut
2710: 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f  hor disclaims co
2720: 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20  pyright to this 
2730: 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e  source code.  In
2740: 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c   place of.** a l
2750: 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72  egal notice, her
2760: 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a  e is a blessing:
2770: 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f  .**.**    May yo
2780: 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f  u do good and no
2790: 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61  t evil..**    Ma
27a0: 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69  y you find forgi
27b0: 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73  veness for yours
27c0: 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20  elf and forgive 
27d0: 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61  others..**    Ma
27e0: 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65  y you share free
27f0: 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67  ly, never taking
2800: 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67   more than you g
2810: 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a  ive..**.********
2820: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2830: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2840: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2850: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2860: 2a 0a 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72  *.** This header
2870: 20 66 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68   file defines th
2880: 65 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  e interface that
2890: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
28a0: 61 72 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20  ary.** presents 
28b0: 74 6f 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61  to client progra
28c0: 6d 73 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63  ms.  If a C-func
28d0: 74 69 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c  tion, structure,
28e0: 20 64 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72   datatype,.** or
28f0: 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69   constant defini
2900: 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70  tion does not ap
2910: 70 65 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c  pear in this fil
2920: 65 2c 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a  e, then it is.**
2930: 20 6e 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64   not a published
2940: 20 41 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20   API of SQLite, 
2950: 69 73 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  is subject to ch
2960: 61 6e 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20  ange without.** 
2970: 6e 6f 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75  notice, and shou
2980: 6c 64 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65  ld not be refere
2990: 6e 63 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73  nced by programs
29a0: 20 74 68 61 74 20 75 73 65 20 53 51 4c 69 74 65   that use SQLite
29b0: 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20  ..**.** Some of 
29c0: 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20  the definitions 
29d0: 74 68 61 74 20 61 72 65 20 69 6e 20 74 68 69 73  that are in this
29e0: 20 66 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64   file are marked
29f0: 20 61 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65   as.** "experime
2a00: 6e 74 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65  ntal".  Experime
2a10: 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  ntal interfaces 
2a20: 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77  are normally new
2a30: 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 72 65 63  .** features rec
2a40: 65 6e 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53  ently added to S
2a50: 51 4c 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f  QLite.  We do no
2a60: 74 20 61 6e 74 69 63 69 70 61 74 65 20 63 68 61  t anticipate cha
2a70: 6e 67 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72  nges.** to exper
2a80: 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63  imental interfac
2a90: 65 73 20 62 75 74 20 72 65 73 65 72 76 65 20 74  es but reserve t
2aa0: 68 65 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65  he right to make
2ab0: 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a   minor changes.*
2ac0: 2a 20 69 66 20 65 78 70 65 72 69 65 6e 63 65 20  * if experience 
2ad0: 66 72 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65  from use "in the
2ae0: 20 77 69 6c 64 22 20 73 75 67 67 65 73 74 20 73   wild" suggest s
2af0: 75 63 68 20 63 68 61 6e 67 65 73 20 61 72 65 20  uch changes are 
2b00: 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54  prudent..**.** T
2b10: 68 65 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61  he official C-la
2b20: 6e 67 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d  nguage API docum
2b30: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c  entation for SQL
2b40: 69 74 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a  ite is derived.*
2b50: 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20  * from comments 
2b60: 69 6e 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54  in this file.  T
2b70: 68 69 73 20 66 69 6c 65 20 69 73 20 74 68 65 20  his file is the 
2b80: 61 75 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f  authoritative so
2b90: 75 72 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53  urce.** on how S
2ba0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
2bb0: 20 61 72 65 20 73 75 70 70 6f 73 65 64 20 74 6f   are supposed to
2bc0: 20 6f 70 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20   operate..**.** 
2bd0: 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 69 73  The name of this
2be0: 20 66 69 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66   file under conf
2bf0: 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65  iguration manage
2c00: 6d 65 6e 74 20 69 73 20 22 73 71 6c 69 74 65 2e  ment is "sqlite.
2c10: 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61  h.in"..** The ma
2c20: 6b 65 66 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d  kefile makes som
2c30: 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67 65 73 20  e minor changes 
2c40: 74 6f 20 74 68 69 73 20 66 69 6c 65 20 28 73 75  to this file (su
2c50: 63 68 20 61 73 20 69 6e 73 65 72 74 69 6e 67 0a  ch as inserting.
2c60: 2a 2a 20 74 68 65 20 76 65 72 73 69 6f 6e 20 6e  ** the version n
2c70: 75 6d 62 65 72 29 20 61 6e 64 20 63 68 61 6e 67  umber) and chang
2c80: 65 73 20 69 74 73 20 6e 61 6d 65 20 74 6f 20 22  es its name to "
2c90: 73 71 6c 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a  sqlite3.h" as.**
2ca0: 20 70 61 72 74 20 6f 66 20 74 68 65 20 62 75 69   part of the bui
2cb0: 6c 64 20 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23  ld process..*/.#
2cc0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 33 5f 48  ifndef SQLITE3_H
2cd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
2ce0: 5f 48 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  _H.#include <std
2cf0: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
2d00: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
2d10: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
2d20: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
2d30: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
2d40: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
2d50: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30  om C++..*/.#if 0
2d60: 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65  .extern "C" {.#e
2d70: 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50 72 6f  ndif.../*.** Pro
2d80: 76 69 64 65 20 74 68 65 20 61 62 69 6c 69 74 79  vide the ability
2d90: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c 69 6e   to override lin
2da0: 6b 61 67 65 20 66 65 61 74 75 72 65 73 20 6f 66  kage features of
2db0: 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 2e 0a   the interface..
2dc0: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
2dd0: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e  E_EXTERN.# defin
2de0: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  e SQLITE_EXTERN 
2df0: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 23 69  extern.#endif.#i
2e00: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49  fndef SQLITE_API
2e10: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2e20: 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69 66 6e  _API.#endif.#ifn
2e30: 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45 43 4c  def SQLITE_CDECL
2e40: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2e50: 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a 23 69  _CDECL.#endif.#i
2e60: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49  fndef SQLITE_API
2e70: 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20 53 51  CALL.# define SQ
2e80: 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23 65 6e  LITE_APICALL.#en
2e90: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
2ea0: 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64 65 66  TE_STDCALL.# def
2eb0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41  ine SQLITE_STDCA
2ec0: 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43 41 4c  LL SQLITE_APICAL
2ed0: 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66  L.#endif.#ifndef
2ee0: 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b   SQLITE_CALLBACK
2ef0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2f00: 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64 69 66  _CALLBACK.#endif
2f10: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
2f20: 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e 65 20  SYSAPI.# define 
2f30: 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a 23 65  SQLITE_SYSAPI.#e
2f40: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
2f50: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
2f60: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
2f70: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
2f80: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
2f90: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
2fa0: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
2fb0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
2fc0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
2fd0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
2fe0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
2ff0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
3000: 79 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  y are supported 
3010: 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a  for backwards.**
3020: 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f   compatibility o
3030: 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  nly.  Applicatio
3040: 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64  n writers should
3050: 20 62 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a   be aware that.*
3060: 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  * experimental i
3070: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 73 75  nterfaces are su
3080: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
3090: 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65  in point release
30a0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d  s..**.** These m
30b0: 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65  acros used to re
30c0: 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73  solve to various
30d0: 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c   kinds of compil
30e0: 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a  er magic that.**
30f0: 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20   would generate 
3100: 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73  warning messages
3110: 20 77 68 65 6e 20 74 68 65 79 20 77 65 72 65 20   when they were 
3120: 75 73 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a  used.  But that.
3130: 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  ** compiler magi
3140: 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72  c ended up gener
3150: 61 74 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75  ating such a flu
3160: 72 72 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72  rry of bug repor
3170: 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61  ts.** that we ha
3180: 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20  ve taken it all 
3190: 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63  out and gone bac
31a0: 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c  k to using simpl
31b0: 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73  e.** noop macros
31c0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
31d0: 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23  ITE_DEPRECATED.#
31e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58  define SQLITE_EX
31f0: 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a  PERIMENTAL../*.*
3200: 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65 20 73  * Ensure these s
3210: 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20  ymbols were not 
3220: 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20  defined by some 
3230: 70 72 65 76 69 6f 75 73 20 68 65 61 64 65 72 20  previous header 
3240: 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  file..*/.#ifdef 
3250: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
3260: 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45   undef SQLITE_VE
3270: 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66  RSION.#endif.#if
3280: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
3290: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65  ON_NUMBER.# unde
32a0: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
32b0: 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a  _NUMBER.#endif..
32c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
32d0: 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62  Compile-Time Lib
32e0: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
32f0: 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  bers.**.** ^(The
3300: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
3310: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
3320: 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71   macro in the sq
3330: 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a  lite3.h header.*
3340: 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61  * evaluates to a
3350: 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20   string literal 
3360: 74 68 61 74 20 69 73 20 74 68 65 20 53 51 4c 69  that is the SQLi
3370: 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68  te version in th
3380: 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59  e.** format "X.Y
3390: 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73 20 74  .Z" where X is t
33a0: 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e  he major version
33b0: 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20   number (always 
33c0: 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33  3 for.** SQLite3
33d0: 29 20 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d  ) and Y is the m
33e0: 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d  inor version num
33f0: 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65  ber and Z is the
3400: 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e   release number.
3410: 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  )^.** ^(The [SQL
3420: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
3430: 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ER] C preprocess
3440: 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65  or macro resolve
3450: 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a  s to an integer.
3460: 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61 6c 75  ** with the valu
3470: 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59  e (X*1000000 + Y
3480: 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65  *1000 + Z) where
3490: 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65   X, Y, and Z are
34a0: 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d   the same.** num
34b0: 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51  bers used in [SQ
34c0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e  LITE_VERSION].)^
34d0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56  .** The SQLITE_V
34e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f  ERSION_NUMBER fo
34f0: 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65  r any given rele
3500: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ase of SQLite wi
3510: 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61  ll also.** be la
3520: 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 72 65  rger than the re
3530: 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68  lease from which
3540: 20 69 74 20 69 73 20 64 65 72 69 76 65 64 2e 20   it is derived. 
3550: 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a   Either Y will.*
3560: 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61  * be held consta
3570: 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65  nt and Z will be
3580: 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20   incremented or 
3590: 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69  else Y will be i
35a0: 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e  ncremented.** an
35b0: 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65  d Z will be rese
35c0: 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  t to zero..**.**
35d0: 20 53 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33   Since version 3
35e0: 2e 36 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f  .6.18, SQLite so
35f0: 75 72 63 65 20 63 6f 64 65 20 68 61 73 20 62 65  urce code has be
3600: 65 6e 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  en stored in the
3610: 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74  .** <a href="htt
3620: 70 3a 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73  p://www.fossil-s
3630: 63 6d 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20  cm.org/">Fossil 
3640: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
3650: 6e 61 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74  nagement.** syst
3660: 65 6d 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51  em</a>.  ^The SQ
3670: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d  LITE_SOURCE_ID m
3680: 61 63 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74  acro evaluates t
3690: 6f 0a 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68  o.** a string wh
36a0: 69 63 68 20 69 64 65 6e 74 69 66 69 65 73 20 61  ich identifies a
36b0: 20 70 61 72 74 69 63 75 6c 61 72 20 63 68 65 63   particular chec
36c0: 6b 2d 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a  k-in of SQLite.*
36d0: 2a 20 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e  * within its con
36e0: 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67  figuration manag
36f0: 65 6d 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e  ement system.  ^
3700: 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  The SQLITE_SOURC
3710: 45 5f 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63  E_ID.** string c
3720: 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74 65  ontains the date
3730: 20 61 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65   and time of the
3740: 20 63 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20   check-in (UTC) 
3750: 61 6e 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68  and an SHA1.** h
3760: 61 73 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72  ash of the entir
3770: 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a  e source tree..*
3780: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
3790: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
37a0: 6f 6e 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  on()],.** [sqlit
37b0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
37c0: 6d 62 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65  mber()], [sqlite
37d0: 33 5f 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a  3_sourceid()],.*
37e0: 2a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  * [sqlite_versio
37f0: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
3800: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
3810: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
3820: 5f 56 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20  _VERSION        
3830: 22 33 2e 31 34 2e 32 22 0a 23 64 65 66 69 6e 65  "3.14.2".#define
3840: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
3850: 4e 55 4d 42 45 52 20 33 30 31 34 30 30 32 0a 23  NUMBER 3014002.#
3860: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f  define SQLITE_SO
3870: 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 32 30  URCE_ID      "20
3880: 31 36 2d 30 39 2d 31 32 20 31 38 3a 35 30 3a 34  16-09-12 18:50:4
3890: 39 20 32 39 64 62 65 66 34 62 38 35 38 35 66 37  9 29dbef4b8585f7
38a0: 35 33 38 36 31 61 33 36 64 36 64 64 31 30 32 63  53861a36d6dd102c
38b0: 61 36 33 34 31 39 37 62 64 36 22 0a 0a 2f 2a 0a  a634197bd6"../*.
38c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
38d0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
38e0: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a  rsion Numbers.**
38f0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
3900: 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69  e3_version, sqli
3910: 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a  te3_sourceid.**.
3920: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61  ** These interfa
3930: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20  ces provide the 
3940: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
3950: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   as the [SQLITE_
3960: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51  VERSION],.** [SQ
3970: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
3980: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  BER], and [SQLIT
3990: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
39a0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
39b0: 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73  os.** but are as
39c0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
39d0: 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61  e library instea
39e0: 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20  d of the header 
39f0: 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75  file.  ^(Cautiou
3a00: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73  s.** programmers
3a10: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61   might include a
3a20: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
3a30: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ts in their appl
3a40: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65  ication to.** ve
3a50: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73  rify that values
3a60: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
3a70: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  se interfaces ma
3a80: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69  tch the macros i
3a90: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c  n.** the header,
3aa0: 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72 65   and thus ensure
3ab0: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63   that the applic
3ac0: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70  ation is.** comp
3ad0: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69  iled with matchi
3ae0: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68  ng library and h
3af0: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a  eader files..**.
3b00: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
3b10: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20  pre>.** assert( 
3b20: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
3b30: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c  on_number()==SQL
3b40: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
3b50: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  ER );.** assert(
3b60: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
3b70: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54  sourceid(),SQLIT
3b80: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20  E_SOURCE_ID)==0 
3b90: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
3ba0: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62  rcmp(sqlite3_lib
3bb0: 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45  version(),SQLITE
3bc0: 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a  _VERSION)==0 );.
3bd0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
3be0: 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
3bf0: 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  The sqlite3_vers
3c00: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
3c10: 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74  stant contains t
3c20: 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49  he text of [SQLI
3c30: 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d  TE_VERSION].** m
3c40: 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69  acro.  ^The sqli
3c50: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
3c60: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
3c70: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
3c80: 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c  he.** to the sql
3c90: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
3ca0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
3cb0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
3cc0: 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e  version().** fun
3cd0: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65  ction is provide
3ce0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c  d for use in DLL
3cf0: 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72  s since DLL user
3d00: 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74  s usually do not
3d10: 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20   have.** direct 
3d20: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67  access to string
3d30: 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69   constants withi
3d40: 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65  n the DLL.  ^The
3d50: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  .** sqlite3_libv
3d60: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20  ersion_number() 
3d70: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
3d80: 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61   an integer equa
3d90: 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  l to.** [SQLITE_
3da0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
3db0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
3dc0: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
3dd0: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
3de0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
3df0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
3e00: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
3e10: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
3e20: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
3e30: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
3e40: 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  or macro..**.** 
3e50: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
3e60: 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64  e_version()] and
3e70: 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f   [sqlite_source_
3e80: 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  id()]..*/.SQLITE
3e90: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
3ea0: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
3eb0: 5d 20 3d 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ] = SQLITE_VERSI
3ec0: 4f 4e 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  ON;.SQLITE_API c
3ed0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
3ee0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f  e3_libversion(vo
3ef0: 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
3f00: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
3f10: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69  te3_sourceid(voi
3f20: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
3f30: 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  nt sqlite3_libve
3f40: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69  rsion_number(voi
3f50: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
3f60: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
3f70: 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f  brary Compilatio
3f80: 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f  n Options Diagno
3f90: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stics.**.** ^The
3fa0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
3fb0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75  option_used() fu
3fc0: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30  nction returns 0
3fd0: 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61   or 1 .** indica
3fe0: 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65  ting whether the
3ff0: 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f   specified optio
4000: 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74  n was defined at
4010: 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d   .** compile tim
4020: 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  e.  ^The SQLITE_
4030: 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f   prefix may be o
4040: 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
4050: 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20  .** option name 
4060: 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65  passed to sqlite
4070: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
4080: 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20  used().  .**.** 
4090: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
40a0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
40b0: 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73   function allows
40c0: 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76   iterating.** ov
40d0: 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f  er the list of o
40e0: 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65  ptions that were
40f0: 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70   defined at comp
4100: 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72  ile time by.** r
4110: 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74  eturning the N-t
4120: 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f  h compile time o
4130: 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e  ption string.  ^
4140: 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  If N is out of r
4150: 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  ange,.** sqlite3
4160: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
4170: 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  et() returns a N
4180: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
4190: 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70  he SQLITE_ .** p
41a0: 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64  refix is omitted
41b0: 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67   from any string
41c0: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a  s returned by .*
41d0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  * sqlite3_compil
41e0: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a  eoption_get()..*
41f0: 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f  *.** ^Support fo
4200: 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63  r the diagnostic
4210: 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74   functions sqlit
4220: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
4230: 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73  _used().** and s
4240: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
4250: 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62  tion_get() may b
4260: 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65  e omitted by spe
4270: 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20  cifying the .** 
4280: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d  [SQLITE_OMIT_COM
4290: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
42a0: 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70  ] option at comp
42b0: 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ile time..**.** 
42c0: 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75  See also: SQL fu
42d0: 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f  nctions [sqlite_
42e0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
42f0: 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
4300: 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  lite_compileopti
4310: 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68  on_get()] and th
4320: 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f  e [compile_optio
4330: 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23  ns pragma]..*/.#
4340: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
4350: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e  IT_COMPILEOPTION
4360: 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50  _DIAGS.SQLITE_AP
4370: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
4380: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
4390: 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70  (const char *zOp
43a0: 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41  tName);.SQLITE_A
43b0: 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
43c0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
43d0: 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b  tion_get(int N);
43e0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
43f0: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f  API3REF: Test To
4400: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72   See If The Libr
4410: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66  ary Is Threadsaf
4420: 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
4430: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
4440: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
4450: 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f  ns zero if and o
4460: 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65  nly if.** SQLite
4470: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
4480: 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65  th mutexing code
4490: 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20   omitted due to 
44a0: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
44b0: 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69  HREADSAFE] compi
44c0: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62  le-time option b
44d0: 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a  eing set to 0..*
44e0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20  *.** SQLite can 
44f0: 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  be compiled with
4500: 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65   or without mute
4510: 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68  xes.  When.** th
4520: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
4530: 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65  SAFE] C preproce
4540: 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20  ssor macro is 1 
4550: 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a  or 2, mutexes.**
4560: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64   are enabled and
4570: 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61   SQLite is threa
4580: 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65  dsafe.  When the
4590: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
45a0: 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73  ADSAFE] macro is
45b0: 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65   0, .** the mute
45c0: 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e  xes are omitted.
45d0: 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75    Without the mu
45e0: 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74  texes, it is not
45f0: 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20   safe.** to use 
4600: 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e  SQLite concurren
4610: 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68  tly from more th
4620: 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a  an one thread..*
4630: 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75  *.** Enabling mu
4640: 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d  texes incurs a m
4650: 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72  easurable perfor
4660: 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a  mance penalty..*
4670: 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69 73  * So if speed is
4680: 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72   of utmost impor
4690: 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20  tance, it makes 
46a0: 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65  sense to disable
46b0: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e  .** the mutexes.
46c0: 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75    But for maximu
46d0: 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65  m safety, mutexe
46e0: 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62  s should be enab
46f0: 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  led..** ^The def
4700: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73  ault behavior is
4710: 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20   for mutexes to 
4720: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  be enabled..**.*
4730: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
4740: 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79 20   can be used by 
4750: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
4760: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
4770: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20   the.** version 
4780: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  of SQLite that i
4790: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61  t is linking aga
47a0: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65  inst was compile
47b0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65  d with.** the de
47c0: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66  sired setting of
47d0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
47e0: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a  EADSAFE] macro..
47f0: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
4800: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74  face only report
4810: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  s on the compile
4820: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74  -time mutex sett
4830: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  ing.** of the [S
4840: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
4850: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69  ] flag.  If SQLi
4860: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
4870: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48  ith.** SQLITE_TH
4880: 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32  READSAFE=1 or =2
4890: 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72   then mutexes ar
48a0: 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
48b0: 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20  ault but.** can 
48c0: 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74  be fully or part
48d0: 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75  ially disabled u
48e0: 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b  sing a call to [
48f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
4900: 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65  ].** with the ve
4910: 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  rbs [SQLITE_CONF
4920: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
4930: 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  , [SQLITE_CONFIG
4940: 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a  _MULTITHREAD],.*
4950: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  * or [SQLITE_CON
4960: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e  FIG_SERIALIZED].
4970: 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76    ^(The return v
4980: 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73  alue of the.** s
4990: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
49a0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  e() function sho
49b0: 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70  ws only the comp
49c0: 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67  ile-time setting
49d0: 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61   of.** thread sa
49e0: 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75  fety, not any ru
49f0: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74  n-time changes t
4a00: 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d  o that setting m
4a10: 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65  ade by.** sqlite
4a20: 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f  3_config(). In o
4a30: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
4a40: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
4a50: 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  m sqlite3_thread
4a60: 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63  safe().** is unc
4a70: 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20  hanged by calls 
4a80: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
4a90: 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  g().)^.**.** See
4aa0: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
4ab0: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74  mode] documentat
4ac0: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
4ad0: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
4ae0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
4af0: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  t sqlite3_thread
4b00: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  safe(void);../*.
4b10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
4b20: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
4b30: 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f   Handle.** KEYWO
4b40: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63  RDS: {database c
4b50: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61  onnection} {data
4b60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
4b70: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65  }.**.** Each ope
4b80: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
4b90: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  e is represented
4ba0: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   by a pointer to
4bb0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a   an instance of.
4bc0: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74  ** the opaque st
4bd0: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73  ructure named "s
4be0: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20  qlite3".  It is 
4bf0: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20  useful to think 
4c00: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a  of an sqlite3.**
4c10: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f   pointer as an o
4c20: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c  bject.  The [sql
4c30: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
4c40: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
4c50: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
4c60: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
4c70: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20  erfaces are its 
4c80: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e  constructors, an
4c90: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
4ca0: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
4cb0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20  te3_close_v2()] 
4cc0: 61 72 65 20 69 74 73 20 64 65 73 74 72 75 63 74  are its destruct
4cd0: 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72 65 20  ors.  There are 
4ce0: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e  many other.** in
4cf0: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61  terfaces (such a
4d00: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  s.** [sqlite3_pr
4d10: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
4d20: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
4d30: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a  ction()], and.**
4d40: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
4d50: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d  imeout()] to nam
4d60: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61  e but three) tha
4d70: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e  t are methods on
4d80: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f   an.** sqlite3 o
4d90: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65  bject..*/.typede
4da0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
4db0: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a   sqlite3;../*.**
4dc0: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
4dd0: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a  t Integer Types.
4de0: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
4df0: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
4e00: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
4e10: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
4e20: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
4e30: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
4e40: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
4e50: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
4e60: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
4e70: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
4e80: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
4e90: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
4ea0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
4eb0: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
4ec0: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
4ed0: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69  ferred type defi
4ee0: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20  nitions..** The 
4ef0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64  sqlite_int64 and
4f00: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
4f10: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74  ypes are support
4f20: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
4f30: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
4f40: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y only..**.** ^T
4f50: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  he sqlite3_int64
4f60: 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36   and sqlite_int6
4f70: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
4f80: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
4f90: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32  .** between -922
4fa0: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38  3372036854775808
4fb0: 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36   and +9223372036
4fc0: 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73  854775807 inclus
4fd0: 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ive.  ^The.** sq
4fe0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64  lite3_uint64 and
4ff0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
5000: 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69  ypes can store i
5010: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a  nteger values .*
5020: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
5030: 2b 31 38 34 34 36 37 34 34 30 37 33 37 30 39 35  +184467440737095
5040: 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e  51615 inclusive.
5050: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
5060: 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74  E_INT64_TYPE.  t
5070: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  ypedef SQLITE_IN
5080: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
5090: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
50a0: 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49 54 45   unsigned SQLITE
50b0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
50c0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 69 66  te_uint64;.#elif
50d0: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45   defined(_MSC_VE
50e0: 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28 5f 5f  R) || defined(__
50f0: 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20 74 79  BORLANDC__).  ty
5100: 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20 73 71  pedef __int64 sq
5110: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
5120: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 5f  pedef unsigned _
5130: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 75 69  _int64 sqlite_ui
5140: 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20 74 79  nt64;.#else.  ty
5150: 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20  pedef long long 
5160: 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  int sqlite_int64
5170: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
5180: 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69  gned long long i
5190: 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nt sqlite_uint64
51a0: 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64 65 66  ;.#endif.typedef
51b0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
51c0: 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74 79 70  lite3_int64;.typ
51d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69 6e 74  edef sqlite_uint
51e0: 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  64 sqlite3_uint6
51f0: 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d  4;../*.** If com
5200: 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70 72 6f  piling for a pro
5210: 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61 63 6b  cessor that lack
5220: 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  s floating point
5230: 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73 75 62   support,.** sub
5240: 73 74 69 74 75 74 65 20 69 6e 74 65 67 65 72 20  stitute integer 
5250: 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70 6f 69  for floating-poi
5260: 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  nt..*/.#ifdef SQ
5270: 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49  LITE_OMIT_FLOATI
5280: 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66 69 6e  NG_POINT.# defin
5290: 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  e double sqlite3
52a0: 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a 0a 2f  _int64.#endif../
52b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
52c0: 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62 61 73  losing A Databas
52d0: 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e Connection.** 
52e0: 44 45 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69  DESTRUCTOR: sqli
52f0: 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
5300: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
5310: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
5320: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
5330: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
5340: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
5350: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
5360: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
5370: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
5380: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
5390: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
53a0: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71  K] if.** the [sq
53b0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
53c0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
53d0: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
53e0: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65  associated.** re
53f0: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c  sources are deal
5400: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  located..**.** ^
5410: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
5420: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73  connection is as
5430: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e  sociated with un
5440: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
5450: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  ed.** statements
5460: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73   or unfinished s
5470: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62  qlite3_backup ob
5480: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74  jects then sqlit
5490: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69  e3_close().** wi
54a0: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74  ll leave the dat
54b0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
54c0: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e   open and return
54d0: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
54e0: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
54f0: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
5500: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  led with unfinal
5510: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74  ized prepared st
5520: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f  atements.** and/
5530: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
5540: 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74  lite3_backups, t
5550: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
5560: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f   connection beco
5570: 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62  mes.** an unusab
5580: 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63  le "zombie" whic
5590: 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  h will automatic
55a0: 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61  ally be dealloca
55b0: 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  ted when the.** 
55c0: 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74  last prepared st
55d0: 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
55e0: 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74  ized or the last
55f0: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
5600: 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20  is.** finished. 
5610: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f   The sqlite3_clo
5620: 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  se_v2() interfac
5630: 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  e is intended fo
5640: 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f  r use with.** ho
5650: 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61  st languages tha
5660: 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f  t are garbage co
5670: 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65  llected, and whe
5680: 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20  re the order in 
5690: 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63  which.** destruc
56a0: 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20  tors are called 
56b0: 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
56c0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
56d0: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
56e0: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
56f0: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
5700: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
5710: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
5720: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d  b_close | close]
5730: 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   all [BLOB handl
5740: 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  es], and .** [sq
5750: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e  lite3_backup_fin
5760: 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c  ish | finish] al
5770: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  l [sqlite3_backu
5780: 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63  p] objects assoc
5790: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
57a0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
57b0: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
57c0: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
57d0: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66  the object.  ^If
57e0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
57f0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
5800: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
5810: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
5820: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
5830: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
5840: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
5850: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
5860: 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69   and/or.** [sqli
5870: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
5880: 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75  cts then it retu
5890: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
58a0: 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61  and the dealloca
58b0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75  tion.** of resou
58c0: 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64  rces is deferred
58d0: 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70   until all [prep
58e0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
58f0: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
5900: 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ,.** and [sqlite
5910: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
5920: 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72  s are also destr
5930: 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  oyed..**.** ^If 
5940: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
5950: 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64  ect is destroyed
5960: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63   while a transac
5970: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a  tion is open,.**
5980: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
5990: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
59a0: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
59b0: 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d  *.** The C param
59c0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
59d0: 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b  _close(C)] and [
59e0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
59f0: 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  (C)].** must be 
5a00: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
5a10: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
5a20: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
5a30: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
5a40: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
5a50: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
5a60: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
5a70: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
5a80: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
5a90: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
5aa0: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  sed..** ^Calling
5ab0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
5ac0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   or sqlite3_clos
5ad0: 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
5ae0: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72  LL pointer.** ar
5af0: 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d  gument is a harm
5b00: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53  less no-op..*/.S
5b10: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
5b20: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69  lite3_close(sqli
5b30: 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
5b40: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  I int sqlite3_cl
5b50: 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a 29  ose_v2(sqlite3*)
5b60: 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70  ;../*.** The typ
5b70: 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b  e for a callback
5b80: 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
5b90: 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e 64  is is legacy and
5ba0: 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49 74   deprecated.  It
5bb0: 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f 72   is included for
5bc0: 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63   historical.** c
5bd0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e 64  ompatibility and
5be0: 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74   is not document
5bf0: 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69  ed..*/.typedef i
5c00: 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c  nt (*sqlite3_cal
5c10: 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74  lback)(void*,int
5c20: 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29  ,char**, char**)
5c30: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
5c40: 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65 72  F: One-Step Quer
5c50: 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74 65  y Execution Inte
5c60: 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a  rface.** METHOD:
5c70: 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
5c80: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
5c90: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
5ca0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
5cb0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
5cc0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
5cd0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
5ce0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
5cf0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
5d00: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
5d10: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
5d20: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
5d30: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
5d40: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
5d50: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
5d60: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
5d70: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
5d80: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
5d90: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
5da0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
5db0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
5dc0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
5dd0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
5de0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
5df0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
5e00: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
5e10: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
5e20: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
5e30: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
5e40: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
5e50: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
5e60: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
5e70: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
5e80: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
5e90: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
5ea0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
5eb0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
5ec0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
5ed0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
5ee0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
5ef0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
5f00: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
5f10: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
5f20: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
5f30: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
5f40: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
5f50: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
5f60: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
5f70: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
5f80: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
5f90: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
5fa0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
5fb0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
5fc0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
5fd0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
5fe0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
5ff0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
6000: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
6010: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
6020: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
6030: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
6040: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
6050: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
6060: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
6070: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
6080: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
6090: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
60a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
60b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
60c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
60d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
60e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
60f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
6100: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
6110: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
6120: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
6130: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
6140: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
6150: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
6160: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
6170: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
6180: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
6190: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
61a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
61b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
61c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71  rameter of.** sq
61d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74  lite3_exec() aft
61e0: 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
61f0: 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e  sage string is n
6200: 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e  o longer needed.
6210: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20  .** ^If the 5th 
6220: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
6230: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
6240: 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65  ot NULL and no e
6250: 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20  rrors.** occur, 
6260: 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  then sqlite3_exe
6270: 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69  c() sets the poi
6280: 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20  nter in its 5th 
6290: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
62a0: 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75  NULL before retu
62b0: 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rning..**.** ^If
62c0: 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63   an sqlite3_exec
62d0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  () callback retu
62e0: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
62f0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
6300: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
6310: 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  rns SQLITE_ABORT
6320: 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e   without invokin
6330: 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61  g the callback a
6340: 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68  gain and.** with
6350: 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20  out running any 
6360: 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73  subsequent SQL s
6370: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
6380: 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65   ^The 2nd argume
6390: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
63a0: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
63b0: 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68  k function is th
63c0: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63  e.** number of c
63d0: 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
63e0: 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20  sult.  ^The 3rd 
63f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
6400: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a  sqlite3_exec().*
6410: 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  * callback is an
6420: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
6430: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62  rs to strings ob
6440: 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f  tained as if fro
6450: 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  m.** [sqlite3_co
6460: 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e  lumn_text()], on
6470: 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d  e for each colum
6480: 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65  n.  ^If an eleme
6490: 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c  nt of a.** resul
64a0: 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68  t row is NULL th
64b0: 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  en the correspon
64c0: 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e  ding string poin
64d0: 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73  ter for the.** s
64e0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
64f0: 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c  llback is a NULL
6500: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
6510: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  4th argument to 
6520: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
6530: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
6540: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
6550: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
6560: 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20  s where each.** 
6570: 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73  entry represents
6580: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72   the name of cor
6590: 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c  responding resul
65a0: 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61  t column as obta
65b0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
65c0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
65d0: 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  e()]..**.** ^If 
65e0: 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
65f0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
6600: 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  c() is a NULL po
6610: 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72  inter, a pointer
6620: 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  .** to an empty 
6630: 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69  string, or a poi
6640: 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69  nter that contai
6650: 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61  ns only whitespa
6660: 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51  ce and/or .** SQ
6670: 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e  L comments, then
6680: 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   no SQL statemen
6690: 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64  ts are evaluated
66a0: 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73   and the databas
66b0: 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  e.** is not chan
66c0: 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72  ged..**.** Restr
66d0: 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ictions:.**.** <
66e0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
66f0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
6700: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
6710: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
6720: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
6730: 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61  .**      is a va
6740: 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61  lid and open [da
6750: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
6760: 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  n]..** <li> The 
6770: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
6780: 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 5b   not close the [
6790: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
67a0: 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
67b0: 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31 73  y.**      the 1s
67c0: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
67d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
67e0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
67f0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
6800: 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69  * <li> The appli
6810: 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
6820: 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20 73  modify the SQL s
6830: 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70 61  tatement text pa
6840: 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20  ssed into.**    
6850: 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65    the 2nd parame
6860: 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 65  ter of sqlite3_e
6870: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
6880: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
6890: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  nning..** </ul>.
68a0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
68b0: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
68c0: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20    sqlite3*,     
68d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
68e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
68f0: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
6900: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
6910: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
6920: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6930: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
6940: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
6950: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
6960: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
6970: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
6980: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
6990: 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20    void *,       
69a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
69b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
69c0: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
69d0: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
69e0: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **errmsg     
69f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6a00: 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f           /* Erro
6a10: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
6a20: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
6a30: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
6a40: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
6a50: 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  DS: {result code
6a60: 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a   definitions}.**
6a70: 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20  .** Many SQLite 
6a80: 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
6a90: 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75   an integer resu
6aa0: 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65  lt code from the
6ab0: 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65   set shown.** he
6ac0: 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69  re in order to i
6ad0: 6e 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20  ndicate success 
6ae0: 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a  or failure..**.*
6af0: 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65  * New error code
6b00: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
6b10: 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  n future version
6b20: 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  s of SQLite..**.
6b30: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78  ** See also: [ex
6b40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
6b50: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a  de definitions].
6b60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6b70: 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30  E_OK           0
6b80: 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c     /* Successful
6b90: 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65   result */./* be
6ba0: 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72  ginning-of-error
6bb0: 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e  -codes */.#defin
6bc0: 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20  e SQLITE_ERROR  
6bd0: 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c        1   /* SQL
6be0: 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e   error or missin
6bf0: 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  g database */.#d
6c00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
6c10: 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a  ERNAL     2   /*
6c20: 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20   Internal logic 
6c30: 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20  error in SQLite 
6c40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6c50: 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33  E_PERM         3
6c60: 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72     /* Access per
6c70: 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a  mission denied *
6c80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6c90: 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20  _ABORT        4 
6ca0: 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f    /* Callback ro
6cb0: 75 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20  utine requested 
6cc0: 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66  an abort */.#def
6cd0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20  ine SQLITE_BUSY 
6ce0: 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54          5   /* T
6cf0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
6d00: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
6d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6d20: 4b 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a  KED       6   /*
6d30: 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20   A table in the 
6d40: 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b  database is lock
6d50: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
6d60: 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20  LITE_NOMEM      
6d70: 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f    7   /* A mallo
6d80: 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64  c() failed */.#d
6d90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
6da0: 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a  DONLY     8   /*
6db0: 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74   Attempt to writ
6dc0: 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74  e a readonly dat
6dd0: 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65  abase */.#define
6de0: 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50   SQLITE_INTERRUP
6df0: 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72  T    9   /* Oper
6e00: 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64  ation terminated
6e10: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65   by sqlite3_inte
6e20: 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e  rrupt()*/.#defin
6e30: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20  e SQLITE_IOERR  
6e40: 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d       10   /* Som
6e50: 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49  e kind of disk I
6e60: 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65  /O error occurre
6e70: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
6e80: 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20  ITE_CORRUPT     
6e90: 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  11   /* The data
6ea0: 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20  base disk image 
6eb0: 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a  is malformed */.
6ec0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
6ed0: 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20  OTFOUND    12   
6ee0: 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64  /* Unknown opcod
6ef0: 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c  e in sqlite3_fil
6f00: 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23  e_control() */.#
6f10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
6f20: 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f  LL        13   /
6f30: 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  * Insertion fail
6f40: 65 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62  ed because datab
6f50: 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23  ase is full */.#
6f60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
6f70: 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f  NTOPEN    14   /
6f80: 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e  * Unable to open
6f90: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
6fa0: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
6fb0: 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20  LITE_PROTOCOL   
6fc0: 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73   15   /* Databas
6fd0: 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20  e lock protocol 
6fe0: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
6ff0: 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20   SQLITE_EMPTY   
7000: 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61      16   /* Data
7010: 62 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f  base is empty */
7020: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7030: 53 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20  SCHEMA      17  
7040: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
7050: 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20   schema changed 
7060: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7070: 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38  E_TOOBIG      18
7080: 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20     /* String or 
7090: 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a  BLOB exceeds siz
70a0: 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69  e limit */.#defi
70b0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
70c0: 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62  AINT  19   /* Ab
70d0: 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74  ort due to const
70e0: 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
70f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7100: 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30  E_MISMATCH    20
7110: 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20     /* Data type 
7120: 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66  mismatch */.#def
7130: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ine SQLITE_MISUS
7140: 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c  E      21   /* L
7150: 69 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f  ibrary used inco
7160: 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69  rrectly */.#defi
7170: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20  ne SQLITE_NOLFS 
7180: 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73        22   /* Us
7190: 65 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e  es OS features n
71a0: 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20  ot supported on 
71b0: 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  host */.#define 
71c0: 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20  SQLITE_AUTH     
71d0: 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f     23   /* Autho
71e0: 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20  rization denied 
71f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7200: 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34  E_FORMAT      24
7210: 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20     /* Auxiliary 
7220: 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20  database format 
7230: 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
7240: 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20   SQLITE_RANGE   
7250: 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20      25   /* 2nd 
7260: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
7270: 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66  ite3_bind out of
7280: 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e   range */.#defin
7290: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20  e SQLITE_NOTADB 
72a0: 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c       26   /* Fil
72b0: 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73  e opened that is
72c0: 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
72d0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
72e0: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20  SQLITE_NOTICE   
72f0: 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66     27   /* Notif
7300: 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71  ications from sq
7310: 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23  lite3_log() */.#
7320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41  define SQLITE_WA
7330: 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f  RNING     28   /
7340: 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20  * Warnings from 
7350: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
7360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7370: 52 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20  ROW         100 
7380: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
7390: 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72  () has another r
73a0: 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66  ow ready */.#def
73b0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20  ine SQLITE_DONE 
73c0: 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73         101  /* s
73d0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
73e0: 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
73f0: 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f  ting */./* end-o
7400: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
7410: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7420: 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c  : Extended Resul
7430: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
7440: 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72  RDS: {extended r
7450: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e  esult code defin
7460: 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e  itions}.**.** In
7470: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
7480: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
7490: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
74a0: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30  return one of 30
74b0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73   integer.** [res
74c0: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
74d0: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
74e0: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20   has shown that 
74f0: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65  many of.** these
7500: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
7510: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61  e too coarse-gra
7520: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
7530: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
7540: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
7550: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
7560: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
7570: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
7580: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
7590: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
75a0: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
75b0: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
75c0: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29  3.3.8 and later)
75d0: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70   include.** supp
75e0: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ort for addition
75f0: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  al result codes 
7600: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72  that provide mor
7610: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
7620: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
7630: 65 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65  errors. These [e
7640: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
7650: 6f 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65  odes] are enable
7660: 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a  d or disabled.**
7670: 20 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61   on a per databa
7680: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  se connection ba
7690: 73 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  sis using the.**
76a0: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
76b0: 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
76c0: 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65  )] API.  Or, the
76d0: 20 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66   extended code f
76e0: 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72  or.** the most r
76f0: 65 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20  ecent error can 
7700: 62 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e  be obtained usin
7710: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  g.** [sqlite3_ex
7720: 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
7730: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
7740: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
7750: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7760: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
7770: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7780: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
7790: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
77a0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
77b0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
77c0: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
77d0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
77e0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
77f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7800: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
7810: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7820: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
7830: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7840: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
7850: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7860: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
7870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7880: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
7890: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
78a0: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
78b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
78c0: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
78d0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
78e0: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
78f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7900: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
7910: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
7920: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
7930: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7940: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
7950: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
7960: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
7970: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7980: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
7990: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
79a0: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
79b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
79c0: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
79d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
79e0: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
79f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7a00: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
7a10: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7a20: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
7a30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7a40: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
7a50: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7a60: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
7a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7a80: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
7a90: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
7aa0: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
7ab0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7ac0: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
7ad0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7ae0: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
7af0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7b00: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
7b10: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7b20: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
7b30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7b40: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
7b50: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7b60: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
7b70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7b80: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
7b90: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7ba0: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
7bb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7bc0: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
7bd0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7be0: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
7bf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7c00: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
7c10: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7c20: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
7c30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7c40: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
7c50: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7c60: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
7c70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7c80: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
7c90: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7ca0: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
7cb0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7cc0: 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20  R_DELETE_NOENT  
7cd0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7ce0: 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65  R | (23<<8)).#de
7cf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7d00: 52 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  R_MMAP          
7d10: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7d20: 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65  R | (24<<8)).#de
7d30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7d40: 52 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20  R_GETTEMPPATH   
7d50: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7d60: 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65  R | (25<<8)).#de
7d70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7d80: 52 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20  R_CONVPATH      
7d90: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7da0: 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65  R | (26<<8)).#de
7db0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7dc0: 52 5f 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20  R_VNODE         
7dd0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7de0: 52 20 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65  R | (27<<8)).#de
7df0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7e00: 52 5f 41 55 54 48 20 20 20 20 20 20 20 20 20 20  R_AUTH          
7e10: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7e20: 52 20 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65  R | (28<<8)).#de
7e30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
7e40: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
7e50: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
7e60: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
7e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
7e80: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
7e90: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
7ea0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
7eb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
7ec0: 53 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20  SY_SNAPSHOT     
7ed0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
7ee0: 53 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a  SY   |  (2<<8)).
7ef0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
7f00: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
7f10: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
7f20: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
7f30: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7f40: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
7f50: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7f60: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
7f70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
7f80: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
7f90: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
7fa0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
7fb0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7fc0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f  LITE_CANTOPEN_CO
7fd0: 4e 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51  NVPATH       (SQ
7fe0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
7ff0: 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (4<<8)).#define 
8000: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56  SQLITE_CORRUPT_V
8010: 54 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28  TAB            (
8020: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c  SQLITE_CORRUPT |
8030: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
8040: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
8050: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
8060: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
8070: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
8080: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
8090: 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20  LY_CANTLOCK     
80a0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
80b0: 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  LY | (2<<8)).#de
80c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
80d0: 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  ONLY_ROLLBACK   
80e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
80f0: 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23  ONLY | (3<<8)).#
8100: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
8110: 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20  ADONLY_DBMOVED  
8120: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
8130: 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29  ADONLY | (4<<8))
8140: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8150: 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20  ABORT_ROLLBACK  
8160: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
8170: 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a  ABORT | (2<<8)).
8180: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
8190: 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20  ONSTRAINT_CHECK 
81a0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
81b0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c  ONSTRAINT | (1<<
81c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
81d0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f  TE_CONSTRAINT_CO
81e0: 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49  MMITHOOK   (SQLI
81f0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
8200: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
8210: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
8220: 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28  T_FOREIGNKEY   (
8230: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
8240: 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  T | (3<<8)).#def
8250: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
8260: 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20  RAINT_FUNCTION  
8270: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
8280: 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a  RAINT | (4<<8)).
8290: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
82a0: 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c  ONSTRAINT_NOTNUL
82b0: 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  L      (SQLITE_C
82c0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c  ONSTRAINT | (5<<
82d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
82e0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52  TE_CONSTRAINT_PR
82f0: 49 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49  IMARYKEY   (SQLI
8300: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
8310: 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (6<<8)).#define 
8320: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
8330: 54 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28  T_TRIGGER      (
8340: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
8350: 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66  T | (7<<8)).#def
8360: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
8370: 52 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20  RAINT_UNIQUE    
8380: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
8390: 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a  RAINT | (8<<8)).
83a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
83b0: 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20  ONSTRAINT_VTAB  
83c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
83d0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c  ONSTRAINT | (9<<
83e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
83f0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f  TE_CONSTRAINT_RO
8400: 57 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  WID        (SQLI
8410: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28  TE_CONSTRAINT |(
8420: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
8430: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45  SQLITE_NOTICE_RE
8440: 43 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28  COVER_WAL      (
8450: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20  SQLITE_NOTICE | 
8460: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
8470: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45  SQLITE_NOTICE_RE
8480: 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28  COVER_ROLLBACK (
8490: 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20  SQLITE_NOTICE | 
84a0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
84b0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41  SQLITE_WARNING_A
84c0: 55 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28  UTOINDEX       (
84d0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c  SQLITE_WARNING |
84e0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
84f0: 20 53 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45   SQLITE_AUTH_USE
8500: 52 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  R               
8510: 28 53 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28  (SQLITE_AUTH | (
8520: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
8530: 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45  QLITE_OK_LOAD_PE
8540: 52 4d 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53  RMANENTLY     (S
8550: 51 4c 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38  QLITE_OK | (1<<8
8560: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
8570: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
8580: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
8590: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62  ns.**.** These b
85a0: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  it values are in
85b0: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
85c0: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72  n the.** 3rd par
85d0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
85e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
85f0: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a  ] interface and.
8600: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61  ** in the 4th pa
8610: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
8620: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
8630: 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64  n] method..*/.#d
8640: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
8650: 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20  N_READONLY      
8660: 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f     0x00000001  /
8670: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
8680: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
8690: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
86a0: 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20  N_READWRITE     
86b0: 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f     0x00000002  /
86c0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
86d0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
86e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
86f0: 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20  N_CREATE        
8700: 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f     0x00000004  /
8710: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
8720: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
8730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
8740: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20  N_DELETEONCLOSE 
8750: 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f     0x00000008  /
8760: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
8770: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
8780: 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  N_EXCLUSIVE     
8790: 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f     0x00000010  /
87a0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
87b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
87c0: 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20  N_AUTOPROXY     
87d0: 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f     0x00000020  /
87e0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
87f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
8800: 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20  N_URI           
8810: 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f     0x00000040  /
8820: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
8830: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
8840: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
8850: 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20  N_MEMORY        
8860: 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f     0x00000080  /
8870: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
8880: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
8890: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
88a0: 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20  N_MAIN_DB       
88b0: 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f     0x00000100  /
88c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
88d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
88e0: 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20  N_TEMP_DB       
88f0: 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f     0x00000200  /
8900: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
8910: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
8920: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20  N_TRANSIENT_DB  
8930: 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f     0x00000400  /
8940: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
8950: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
8960: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20  N_MAIN_JOURNAL  
8970: 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f     0x00000800  /
8980: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
8990: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
89a0: 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20  N_TEMP_JOURNAL  
89b0: 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f     0x00001000  /
89c0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
89d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
89e0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20  N_SUBJOURNAL    
89f0: 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f     0x00002000  /
8a00: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
8a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
8a20: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
8a30: 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f     0x00004000  /
8a40: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64  * VFS only */.#d
8a50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
8a60: 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20  N_NOMUTEX       
8a70: 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f     0x00008000  /
8a80: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
8a90: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
8aa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
8ab0: 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20  N_FULLMUTEX     
8ac0: 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f     0x00010000  /
8ad0: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
8ae0: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
8af0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
8b00: 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  N_SHAREDCACHE   
8b10: 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f     0x00020000  /
8b20: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
8b30: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
8b40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
8b50: 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20  N_PRIVATECACHE  
8b60: 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f     0x00040000  /
8b70: 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33  * Ok for sqlite3
8b80: 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64  _open_v2() */.#d
8b90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45  efine SQLITE_OPE
8ba0: 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  N_WAL           
8bb0: 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f     0x00080000  /
8bc0: 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  * VFS only */../
8bd0: 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20  * Reserved:     
8be0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8bf0: 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a      0x00F00000 *
8c00: 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
8c10: 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63  F: Device Charac
8c20: 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20  teristics.**.** 
8c30: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
8c40: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
8c50: 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  d of the [sqlite
8c60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  3_io_methods].**
8c70: 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20   object returns 
8c80: 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
8c90: 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20   is a vector of 
8ca0: 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c  these.** bit val
8cb0: 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49  ues expressing I
8cc0: 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69  /O characteristi
8cd0: 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73  cs of the mass s
8ce0: 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65  torage.** device
8cf0: 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20   that holds the 
8d00: 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73  file that the [s
8d10: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8d20: 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e  s].** refers to.
8d30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
8d40: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
8d50: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8d60: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
8d70: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
8d80: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8d90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8da0: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
8db0: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
8dc0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
8dd0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
8de0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
8df0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
8e00: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
8e10: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
8e20: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
8e30: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8e40: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8e50: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
8e60: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
8e70: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8e80: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
8e90: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8ea0: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
8eb0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
8ec0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
8ed0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
8ee0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
8ef0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8f00: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
8f10: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8f20: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8f30: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
8f40: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
8f50: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
8f60: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54   to xWrite().  T
8f70: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8f80: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
8f90: 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61  ITE property mea
8fa0: 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72  ns that.** after
8fb0: 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e   reboot followin
8fc0: 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77  g a crash or pow
8fd0: 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c  er loss, the onl
8fe0: 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20  y bytes in a.** 
8ff0: 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77  file that were w
9000: 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70  ritten at the ap
9010: 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20  plication level 
9020: 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67  might have chang
9030: 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61  ed.** and that a
9040: 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65  djacent bytes, e
9050: 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e  ven bytes within
9060: 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72   the same sector
9070: 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65   are.** guarante
9080: 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67  ed to be unchang
9090: 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ed.  The SQLITE_
90a0: 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c  IOCAP_UNDELETABL
90b0: 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66  E_WHEN_OPEN.** f
90c0: 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74 68 61  lag indicate tha
90d0: 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20  t a file cannot 
90e0: 62 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  be deleted when 
90f0: 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51  open.  The.** SQ
9100: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
9110: 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61  ABLE flag indica
9120: 74 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c  tes that the fil
9130: 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d  e is on.** read-
9140: 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63  only media and c
9150: 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
9160: 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73   even by process
9170: 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61  es with.** eleva
9180: 74 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a  ted privileges..
9190: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
91a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
91b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
91c0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
91d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
91e0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
91f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
9200: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9210: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
9220: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
9230: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
9240: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
9250: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
9260: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
9270: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9280: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
9290: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
92a0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
92b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
92c0: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
92d0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
92e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
92f0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
9300: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
9310: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
9320: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
9330: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
9340: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
9350: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
9360: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
9370: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
9380: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
9390: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
93a0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
93b0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
93c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
93d0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
93e0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
93f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
9400: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
9410: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
9420: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
9430: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
9440: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
9450: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64     0x00001000.#d
9460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
9470: 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20  AP_IMMUTABLE    
9480: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
9490: 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  2000../*.** CAPI
94a0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
94b0: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
94c0: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
94d0: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
94e0: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
94f0: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
9500: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
9510: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
9520: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
9530: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
9540: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
9550: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
9560: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9570: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
9580: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
9590: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
95a0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
95b0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
95c0: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
95d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
95e0: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
95f0: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
9600: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
9610: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
9620: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
9630: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
9640: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
9650: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
9660: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
9670: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
9680: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
9690: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
96a0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
96b0: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
96c0: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
96d0: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
96e0: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
96f0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
9700: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
9710: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
9720: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
9730: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
9740: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
9750: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
9760: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
9770: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
9780: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
9790: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
97a0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
97b0: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
97c0: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
97d0: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
97e0: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
97f0: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
9800: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
9810: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
9820: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
9830: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
9840: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
9850: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
9860: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
9870: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
9880: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
9890: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
98a0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
98b0: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
98c0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
98d0: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
98e0: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
98f0: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
9900: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
9910: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
9920: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
9930: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
9940: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
9950: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
9960: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
9970: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
9980: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
9990: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
99a0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
99b0: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
99c0: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
99d0: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
99e0: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
99f0: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
9a00: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
9a10: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
9a20: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
9a30: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
9a40: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
9a50: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
9a60: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
9a70: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
9a80: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
9a90: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
9aa0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
9ab0: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
9ac0: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
9ad0: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
9ae0: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
9af0: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
9b00: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
9b10: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
9b20: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
9b30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
9b40: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
9b50: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
9b60: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
9b70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
9b80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9b90: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
9ba0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
9bb0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
9bc0: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
9bd0: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
9be0: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
9bf0: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
9c00: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
9c10: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
9c20: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
9c30: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
9c40: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
9c50: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
9c60: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
9c70: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
9c80: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
9c90: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
9ca0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
9cb0: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
9cc0: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
9cd0: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
9ce0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
9cf0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
9d00: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
9d10: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
9d20: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
9d30: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
9d40: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
9d50: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
9d60: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
9d70: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
9d80: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
9d90: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
9da0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
9db0: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
9dc0: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
9dd0: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
9de0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
9df0: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
9e00: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
9e10: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
9e20: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
9e30: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
9e40: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
9e50: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
9e60: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
9e70: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
9e80: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
9e90: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
9ea0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
9eb0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
9ec0: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
9ed0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
9ee0: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
9ef0: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
9f00: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
9f10: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
9f20: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
9f30: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
9f40: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
9f50: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
9f60: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9f70: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
9f80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
9f90: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
9fa0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
9fb0: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
9fc0: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
9fd0: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
9fe0: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
9ff0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
a000: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
a010: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
a020: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
a030: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
a040: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
a050: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
a060: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
a070: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
a080: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
a090: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
a0a0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
a0b0: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
a0c0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
a0d0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
a0e0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
a0f0: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
a100: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
a110: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
a120: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
a130: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
a140: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
a150: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
a160: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
a170: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
a180: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
a190: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
a1a0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
a1b0: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
a1c0: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
a1d0: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
a1e0: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
a1f0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
a200: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
a210: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
a220: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
a230: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
a240: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
a250: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
a260: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
a270: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
a280: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
a290: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
a2a0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
a2b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
a2c0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
a2d0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
a2e0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
a2f0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
a300: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
a310: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
a320: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
a330: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
a340: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
a350: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
a360: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
a370: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
a380: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
a390: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
a3a0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
a3b0: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
a3c0: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
a3d0: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
a3e0: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
a3f0: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
a400: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
a410: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
a420: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
a430: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
a440: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
a450: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
a460: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
a470: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
a480: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
a490: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
a4a0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
a4b0: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
a4c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
a4d0: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
a4e0: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
a4f0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
a500: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
a510: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
a520: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
a530: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
a540: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
a550: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
a560: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
a570: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
a580: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
a590: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
a5a0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
a5b0: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
a5c0: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
a5d0: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
a5e0: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
a5f0: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
a600: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
a610: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
a620: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
a630: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
a640: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
a650: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
a660: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
a670: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
a680: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
a690: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
a6a0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
a6b0: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
a6c0: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
a6d0: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
a6e0: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
a6f0: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
a700: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
a710: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
a720: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
a730: 6f 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f  odes | list of o
a740: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
a750: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
a760: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
a770: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
a780: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
a790: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
a7a0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
a7b0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
a7c0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
a7d0: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
a7e0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
a7f0: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
a800: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
a810: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
a820: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
a830: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
a840: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
a850: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
a860: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
a870: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
a880: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
a890: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
a8a0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
a8b0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
a8c0: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
a8d0: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
a8e0: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
a8f0: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
a900: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
a910: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
a920: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
a930: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
a940: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
a950: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
a960: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
a970: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
a980: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
a990: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
a9a0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
a9b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
a9c0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
a9d0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
a9e0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
a9f0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
aa00: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
aa10: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
aa20: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
aa30: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
aa40: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
aa50: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
aa60: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
aa70: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
aa80: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
aa90: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
aaa0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
aab0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
aac0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
aad0: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
aae0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
aaf0: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
ab00: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
ab10: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
ab20: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
ab30: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
ab40: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
ab50: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
ab60: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
ab70: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
ab80: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
ab90: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
aba0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
abb0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
abc0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
abd0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
abe0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
abf0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
ac00: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
ac10: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
ac20: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
ac30: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
ac40: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
ac50: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
ac60: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
ac70: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
ac80: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
ac90: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
aca0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
acb0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
acc0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
acd0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
ace0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
acf0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
ad00: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
ad10: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
ad20: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
ad30: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
ad40: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
ad50: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
ad60: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
ad70: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
ad80: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
ad90: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
ada0: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
adb0: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
adc0: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
add0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
ade0: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
adf0: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
ae00: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
ae10: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
ae20: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
ae30: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
ae40: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
ae50: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
ae60: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
ae70: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
ae80: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
ae90: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
aea0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
aeb0: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
aec0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
aed0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
aee0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
aef0: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
af00: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
af10: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
af20: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
af30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
af40: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
af50: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
af60: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
af70: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
af80: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
af90: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
afa0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
afb0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
afc0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
afd0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
afe0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
aff0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
b000: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
b010: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
b020: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
b030: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
b040: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
b050: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
b060: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
b070: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
b080: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
b090: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
b0a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
b0b0: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
b0c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
b0d0: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
b0e0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
b0f0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
b100: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
b110: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
b120: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
b130: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
b140: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
b150: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
b160: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
b170: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
b180: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
b190: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
b1a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
b1b0: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
b1c0: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
b1d0: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
b1e0: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
b1f0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
b200: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
b210: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
b220: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
b230: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
b240: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
b250: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
b260: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
b270: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
b280: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
b290: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
b2a0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
b2b0: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
b2c0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
b2d0: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
b2e0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
b2f0: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
b300: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
b310: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
b320: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
b330: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
b340: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
b350: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
b360: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
b370: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b  rol Opcodes.** K
b380: 45 59 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63  EYWORDS: {file c
b390: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20  ontrol opcodes} 
b3a0: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
b3b0: 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  code}.**.** Thes
b3c0: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
b3d0: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
b3e0: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
b3f0: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
b400: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
b410: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
b420: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
b430: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
b440: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
b450: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ace..**.** <ul>.
b460: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b470: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
b480: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b490: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
b4a0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
b4b0: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
b4c0: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
b4d0: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
b4e0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
b4f0: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
b500: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
b510: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
b520: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
b530: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
b540: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
b550: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
b560: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
b570: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
b580: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
b590: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
b5a0: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
b5b0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
b5c0: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
b5d0: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
b5e0: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
b5f0: 74 65 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f  testing and is o
b600: 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68  nly available wh
b610: 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  en the SQLITE_TE
b620: 53 54 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  ST.** compile-ti
b630: 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  me option is use
b640: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
b650: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
b660: 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _HINT]].** The [
b670: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
b680: 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69  E_HINT] opcode i
b690: 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  s used by SQLite
b6a0: 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53   to give the VFS
b6b0: 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74  .** layer a hint
b6c0: 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68   of how large th
b6d0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
b6e0: 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20  will grow to be 
b6f0: 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75  during the.** cu
b700: 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f  rrent transactio
b710: 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73  n.  This hint is
b720: 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20   not guaranteed 
b730: 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62  to be accurate b
b740: 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65  ut it.** is ofte
b750: 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e  n close.  The un
b760: 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67  derlying VFS mig
b770: 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65  ht choose to pre
b780: 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73  allocate databas
b790: 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20  e.** file space 
b7a0: 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69  based on this hi
b7b0: 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68  nt in order to h
b7c0: 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68  elp writes to th
b7d0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
b7e0: 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a  le run faster..*
b7f0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
b800: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
b810: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
b820: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
b830: 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  SIZE] opcode is 
b840: 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20  used to request 
b850: 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20  that the VFS.** 
b860: 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e  extends and trun
b870: 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61  cates the databa
b880: 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b  se file in chunk
b890: 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63  s of a size spec
b8a0: 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20  ified.** by the 
b8b0: 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68  user. The fourth
b8c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
b8d0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
b8e0: 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a  ol()] should .**
b8f0: 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74   point to an int
b900: 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20  eger (type int) 
b910: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
b920: 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f  ew chunk-size to
b930: 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20   use.** for the 
b940: 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61  nominated databa
b950: 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64  se. Allocating d
b960: 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61  atabase file spa
b970: 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63  ce in large.** c
b980: 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61  hunks (say 1MB a
b990: 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72  t a time), may r
b9a0: 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65  educe file-syste
b9b0: 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  m fragmentation 
b9c0: 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70  and.** improve p
b9d0: 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f  erformance on so
b9e0: 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a  me systems..**.*
b9f0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ba00: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
ba10: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
ba20: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
ba30: 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73  INTER] opcode is
ba40: 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20   used to obtain 
ba50: 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
ba60: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
ba70: 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69  e] object associ
ba80: 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74  ated with a part
ba90: 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a  icular database.
baa0: 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
bab0: 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45  See also [SQLITE
bac0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
bad0: 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  OINTER]..**.** <
bae0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
baf0: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
bb00: 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  R]].** The [SQLI
bb10: 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c  TE_FCNTL_JOURNAL
bb20: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
bb30: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
bb40: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
bb50: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
bb60: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
bb70: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
bb80: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65   journal file (e
bb90: 69 74 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f  ither.** the [ro
bba0: 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20  llback journal] 
bbb0: 6f 72 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68  or the [write-ah
bbc0: 65 61 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20  ead log]) for a 
bbd0: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
bbe0: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
bbf0: 6e 2e 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51  n.  See also [SQ
bc00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
bc10: 50 4f 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20  POINTER]..**.** 
bc20: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
bc30: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d  TL_SYNC_OMITTED]
bc40: 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69  ].** No longer i
bc50: 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  n use..**.** <li
bc60: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bc70: 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  SYNC]].** The [S
bc80: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
bc90: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
bca0: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
bcb0: 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a   by SQLite and.*
bcc0: 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  * sent to the VF
bcd0: 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65  S immediately be
bce0: 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d  fore the xSync m
bcf0: 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
bd00: 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73   on a.** databas
bd10: 65 20 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f  e file descripto
bd20: 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53  r. Or, if the xS
bd30: 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f  ync method is no
bd40: 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65  t invoked .** be
bd50: 63 61 75 73 65 20 74 68 65 20 75 73 65 72 20 68  cause the user h
bd60: 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51  as configured SQ
bd70: 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50  Lite with .** [P
bd80: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
bd90: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
bda0: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69  ronous=OFF] it i
bdb0: 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61  s invoked in pla
bdc0: 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53  ce .** of the xS
bdd0: 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d  ync method. In m
bde0: 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65 20 70  ost cases, the p
bdf0: 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20  ointer argument 
be00: 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74  passed with.** t
be10: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
be20: 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65   is NULL. Howeve
be30: 72 2c 20 69 66 20 74 68 65 20 64 61 74 61 62 61  r, if the databa
be40: 73 65 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67  se file is being
be50: 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61   synced.** as pa
be60: 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61  rt of a multi-da
be70: 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74  tabase commit, t
be80: 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  he argument poin
be90: 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d  ts to a nul-term
bea0: 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
beb0: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
bec0: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73  transactions mas
bed0: 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  ter-journal file
bee0: 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61   name. VFSes tha
bef0: 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65  t .** do not nee
bf00: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68  d this signal sh
bf10: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
bf20: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
bf30: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a  . Applications .
bf40: 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ** should not ca
bf50: 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ll [sqlite3_file
bf60: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68  _control()] with
bf70: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20   this opcode as 
bf80: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a  doing so may .**
bf90: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
bfa0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
bfb0: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
bfc0: 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20  that do require 
bfd0: 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  it.  .**.** <li>
bfe0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
bff0: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d  OMMIT_PHASETWO]]
c000: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
c010: 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41  FCNTL_COMMIT_PHA
c020: 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73  SETWO] opcode is
c030: 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72   generated inter
c040: 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a  nally by SQLite.
c050: 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74  ** and sent to t
c060: 68 65 20 56 46 53 20 61 66 74 65 72 20 61 20 74  he VFS after a t
c070: 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62  ransaction has b
c080: 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d  een committed im
c090: 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74  mediately.** but
c0a0: 20 62 65 66 6f 72 65 20 74 68 65 20 64 61 74 61   before the data
c0b0: 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64  base is unlocked
c0c0: 2e 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  . VFSes that do 
c0d0: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
c0e0: 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73  gnal.** should s
c0f0: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
c100: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
c110: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
c120: 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  not call.** [sql
c130: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
c140: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
c150: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
c160: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
c170: 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20  e .** operation 
c180: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
c190: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
c1a0: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
c1b0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c1c0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
c1d0: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
c1e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
c1f0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
c200: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
c210: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
c220: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
c230: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
c240: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
c250: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
c260: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
c270: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
c280: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
c290: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
c2a0: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
c2b0: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
c2c0: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
c2d0: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
c2e0: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
c2f0: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
c300: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
c310: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
c320: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
c330: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
c340: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
c350: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
c360: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
c370: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
c380: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
c390: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
c3a0: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
c3b0: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
c3c0: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
c3d0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
c3e0: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
c3f0: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
c400: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
c410: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
c420: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
c430: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
c440: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
c450: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c460: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
c470: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
c480: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
c490: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
c4a0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
c4b0: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
c4c0: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
c4d0: 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74  er i the new ret
c4e0: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65  ry count and the
c4f0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67   second.** integ
c500: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e  er is the delay.
c510: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65    If either inte
c520: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ger is negative,
c530: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e   then the settin
c540: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  g.** is not chan
c550: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20  ged but instead 
c560: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
c570: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20  of that setting 
c580: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e  is written.** in
c590: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74  to the array ent
c5a0: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65  ry, allowing the
c5b0: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73   current retry s
c5c0: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a  ettings to be.**
c5d0: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
c5e0: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61  The zDbName para
c5f0: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64  meter is ignored
c600: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c610: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
c620: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65  ST_WAL]].** ^The
c630: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
c640: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f  ERSIST_WAL] opco
c650: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
c660: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
c670: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41  * persistent [WA
c680: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20  L | Write Ahead 
c690: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42  Log] setting.  B
c6a0: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61  y default, the a
c6b0: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74  uxiliary.** writ
c6c0: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20  e ahead log and 
c6d0: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
c6e0: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61  les used for tra
c6f0: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
c700: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69  .** are automati
c710: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68  cally deleted wh
c720: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f  en the latest co
c730: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20  nnection to the 
c740: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73  database.** clos
c750: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72  es.  Setting per
c760: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
c770: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69   causes those fi
c780: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61  les to persist a
c790: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20  fter.** close.  
c7a0: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66  Persisting the f
c7b0: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77  iles is useful w
c7c0: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73  hen other proces
c7d0: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a  ses that do not.
c7e0: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65  ** have write pe
c7f0: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20  rmission on the 
c800: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69  directory contai
c810: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
c820: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74  e file want.** t
c830: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62  o read the datab
c840: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65  ase file, as the
c850: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20   WAL and shared 
c860: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73  memory files mus
c870: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72  t exist.** in or
c880: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  der for the data
c890: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61  base to be reada
c8a0: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68  ble.  The fourth
c8b0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
c8c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
c8d0: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
c8e0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
c8f0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
c900: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
c910: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
c920: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72  0 to disable per
c930: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
c940: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
c950: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41  persistent.** WA
c960: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  L mode.  If the 
c970: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
c980: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
c990: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
c9a0: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65  urrent.** WAL pe
c9b0: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e  rsistence settin
c9c0: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
c9d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
c9e0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
c9f0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
ca00: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
ca10: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  E_OVERWRITE] opc
ca20: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
ca30: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
ca40: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70  ** persistent "p
ca50: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69  owersafe-overwri
ca60: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65  te" or "PSOW" se
ca70: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57  tting.  The PSOW
ca80: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65   setting.** dete
ca90: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49  rmines the [SQLI
caa0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
cab0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69  FE_OVERWRITE] bi
cac0: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76  t of the.** xDev
cad0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
cae0: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20  cs methods. The 
caf0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
cb00: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
cb10: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
cb20: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
cb30: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
cb40: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
cb50: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
cb60: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
cb70: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  le zero-damage m
cb80: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
cb90: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a  le zero-damage.*
cba0: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  * mode.  If the 
cbb0: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
cbc0: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
cbd0: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
cbe0: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64  urrent.** zero-d
cbf0: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69  amage mode setti
cc00: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
cc10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
cc20: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
cc30: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f   [SQLITE_FCNTL_O
cc40: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
cc50: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   is invoked by S
cc60: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e  QLite after open
cc70: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74  ing.** a write t
cc80: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e  ransaction to in
cc90: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c  dicate that, unl
cca0: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64  ess it is rolled
ccb0: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a   back for some.*
ccc0: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e  * reason, the en
ccd0: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69  tire database fi
cce0: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77  le will be overw
ccf0: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75  ritten by the cu
cd00: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61  rrent .** transa
cd10: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75  ction. This is u
cd20: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70  sed by VACUUM op
cd30: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
cd40: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
cd50: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20  TL_VFSNAME]].** 
cd60: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
cd70: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f  TL_VFSNAME] opco
cd80: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
cd90: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d  o obtain the nam
cda0: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46  es of.** all [VF
cdb0: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20  Ses] in the VFS 
cdc0: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65  stack.  The name
cdd0: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53  s are of all VFS
cde0: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a   shims and the.*
cdf0: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c  * final bottom-l
ce00: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69  evel VFS are wri
ce10: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
ce20: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
ce30: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
ce40: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  oc()] and the re
ce50: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69  sult is stored i
ce60: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  n the char* vari
ce70: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65  able.** that the
ce80: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
ce90: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69  r of [sqlite3_fi
cea0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f  le_control()] po
ceb0: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20  ints to..** The 
cec0: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e  caller is respon
ced0: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
cee0: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65  g the memory whe
cef0: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68  n done.  As with
cf00: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e  .** all file-con
cf10: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68  trol actions, th
cf20: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e  ere is no guaran
cf30: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69  tee that this wi
cf40: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64  ll actually.** d
cf50: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c  o anything.  Cal
cf60: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74  lers should init
cf70: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a  ialize the char*
cf80: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e   variable to a N
cf90: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ULL.** pointer i
cfa0: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65  n case this file
cfb0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20  -control is not 
cfc0: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68  implemented.  Th
cfd0: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  is file-control.
cfe0: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ** is intended f
cff0: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73  or diagnostic us
d000: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  e only..**.** <l
d010: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
d020: 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a  _VFS_POINTER]].*
d030: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
d040: 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52  CNTL_VFS_POINTER
d050: 5d 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61  ] opcode finds a
d060: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
d070: 74 6f 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46  top-level.** [VF
d080: 53 65 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69  Ses] currently i
d090: 6e 20 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72  n use.  ^(The ar
d0a0: 67 75 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73  gument X in.** s
d0b0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
d0c0: 72 6f 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43  rol(db,SQLITE_FC
d0d0: 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c  NTL_VFS_POINTER,
d0e0: 58 29 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66  X) must be.** of
d0f0: 20 74 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f   type "[sqlite3_
d100: 76 66 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20  vfs] **".  This 
d110: 6f 70 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74  opcodes will set
d120: 20 2a 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e   *X.** to a poin
d130: 74 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c  ter to the top-l
d140: 65 76 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e  evel VFS.)^.** ^
d150: 57 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d  When there are m
d160: 75 6c 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d  ultiple VFS shim
d170: 73 20 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20  s in the stack, 
d180: 74 68 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64  this opcode find
d190: 73 20 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d  s the.** upper-m
d1a0: 6f 73 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a  ost shim only..*
d1b0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
d1c0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d  E_FCNTL_PRAGMA]]
d1d0: 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20  .** ^Whenever a 
d1e0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
d1f0: 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e  nt is parsed, an
d200: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
d210: 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20  RAGMA] .** file 
d220: 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20  control is sent 
d230: 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c  to the open [sql
d240: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
d250: 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  t corresponding.
d260: 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ** to the databa
d270: 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68  se file to which
d280: 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74   the pragma stat
d290: 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54  ement refers. ^T
d2a0: 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  he argument.** t
d2b0: 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  o the [SQLITE_FC
d2c0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
d2d0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61   control is an a
d2e0: 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74  rray of.** point
d2f0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28  ers to strings (
d300: 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68  char**) in which
d310: 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d   the second elem
d320: 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79  ent of the array
d330: 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
d340: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e  of the pragma an
d350: 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d  d the third elem
d360: 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ent is the argum
d370: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72  ent to the.** pr
d380: 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20  agma or NULL if 
d390: 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e  the pragma has n
d3a0: 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68  o argument.  ^Th
d3b0: 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e  e handler for an
d3c0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
d3d0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
d3e0: 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f  ontrol can optio
d3f0: 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66  nally make the f
d400: 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  irst element.** 
d410: 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72  of the char** ar
d420: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20  gument point to 
d430: 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65  a string obtaine
d440: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
d450: 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72  mprintf()].** or
d460: 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20   the equivalent 
d470: 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20  and that string 
d480: 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20  will become the 
d490: 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72  result of the pr
d4a0: 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65  agma or.** the e
d4b0: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20  rror message if 
d4c0: 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73  the pragma fails
d4d0: 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51  . ^If the.** [SQ
d4e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
d4f0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
d500: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
d510: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20  NOTFOUND], then 
d520: 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47  normal .** [PRAG
d530: 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63  MA] processing c
d540: 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74  ontinues.  ^If t
d550: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
d560: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
d570: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
d580: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68   [SQLITE_OK], th
d590: 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73  en the parser as
d5a0: 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
d5b0: 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65  * VFS has handle
d5c0: 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73  d the PRAGMA its
d5d0: 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73  elf and the pars
d5e0: 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e  er generates a n
d5f0: 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64  o-op.** prepared
d600: 20 73 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65   statement if re
d610: 73 75 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e  sult string is N
d620: 55 4c 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74  ULL, or that ret
d630: 75 72 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  urns a copy.** o
d640: 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 74 72  f the result str
d650: 69 6e 67 20 69 66 20 74 68 65 20 73 74 72 69 6e  ing if the strin
d660: 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a  g is non-NULL..*
d670: 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
d680: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
d690: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
d6a0: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
d6b0: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
d6c0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
d6d0: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
d6e0: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
d6f0: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
d700: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
d710: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
d720: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
d730: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
d740: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
d750: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
d760: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
d770: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
d780: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
d790: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
d7a0: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
d7b0: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
d7c0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
d7d0: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
d7e0: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
d7f0: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
d800: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
d810: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d820: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
d830: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
d840: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
d850: 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  LER].** file-con
d860: 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f  trol may be invo
d870: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e  ked by SQLite on
d880: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
d890: 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f  le handle.** sho
d8a0: 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73  rtly after it is
d8b0: 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72   opened in order
d8c0: 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75   to provide a cu
d8d0: 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63  stom VFS with ac
d8e0: 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  cess.** to the c
d8f0: 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d  onnections busy-
d900: 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
d910: 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69  . The argument i
d920: 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20  s of type (void 
d930: 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61  **).** - an arra
d940: 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a  y of two (void *
d950: 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69  ) values. The fi
d960: 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74  rst (void *) act
d970: 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20  ually points.** 
d980: 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
d990: 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76   type (int (*)(v
d9a0: 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65  oid *)). In orde
d9b0: 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20  r to invoke the 
d9c0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62  connections.** b
d9d0: 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69  usy-handler, thi
d9e0: 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  s function shoul
d9f0: 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74  d be invoked wit
da00: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f  h the second (vo
da10: 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20  id *) in.** the 
da20: 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c  array as the onl
da30: 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69  y argument. If i
da40: 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  t returns non-ze
da50: 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65  ro, then the ope
da60: 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64  ration.** should
da70: 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20   be retried. If 
da80: 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c  it returns zero,
da90: 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20   the custom VFS 
daa0: 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74  should abandon t
dab0: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70  he.** current op
dac0: 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  eration..**.** <
dad0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
dae0: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d  L_TEMPFILENAME]]
daf0: 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e  .** ^Application
db00: 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20   can invoke the 
db10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
db20: 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65  MPFILENAME] file
db30: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68  -control.** to h
db40: 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72  ave SQLite gener
db50: 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61  ate a.** tempora
db60: 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e  ry filename usin
db70: 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72  g the same algor
db80: 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c  ithm that is fol
db90: 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74  lowed to generat
dba0: 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  e.** temporary f
dbb0: 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d  ilenames for TEM
dbc0: 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68  P tables and oth
dbd0: 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73  er internal uses
dbe0: 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65  .  The.** argume
dbf0: 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63  nt should be a c
dc00: 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c  har** which will
dc10: 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20   be filled with 
dc20: 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20  the filename.** 
dc30: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
dc40: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
dc50: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
dc60: 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65  c()].  The calle
dc70: 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f  r should.** invo
dc80: 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ke [sqlite3_free
dc90: 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c  ()] on the resul
dca0: 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d  t to avoid a mem
dcb0: 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20  ory leak..**.** 
dcc0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
dcd0: 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  TL_MMAP_SIZE]].*
dce0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
dcf0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66  NTL_MMAP_SIZE] f
dd00: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75  ile control is u
dd10: 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20  sed to query or 
dd20: 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d  set the.** maxim
dd30: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
dd40: 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20  es that will be 
dd50: 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d  used for memory-
dd60: 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54  mapped I/O..** T
dd70: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
dd80: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
dd90: 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69  lue of type sqli
dda0: 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a  te3_int64 that.*
ddb0: 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79  * is an advisory
ddc0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
ddd0: 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
dde0: 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d  file to memory m
ddf0: 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e  ap.  The.** poin
de00: 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74 74  ter is overwritt
de10: 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20  en with the old 
de20: 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69  value.  The limi
de30: 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  t is not changed
de40: 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65   if.** the value
de50: 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e   originally poin
de60: 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69  ted to is negati
de70: 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63  ve, and so the c
de80: 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a  urrent limit .**
de90: 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64 20   can be queried 
dea0: 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20  by passing in a 
deb0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67  pointer to a neg
dec0: 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54  ative number.  T
ded0: 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74  his.** file-cont
dee0: 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65  rol is used inte
def0: 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d  rnally to implem
df00: 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  ent [PRAGMA mmap
df10: 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  _size]..**.** <l
df20: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
df30: 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20  _TRACE]].** The 
df40: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52  [SQLITE_FCNTL_TR
df50: 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ACE] file contro
df60: 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69 73  l provides advis
df70: 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ory information.
df80: 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61 62  ** to the VFS ab
df90: 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69 67  out what the hig
dfa0: 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68  her layers of th
dfb0: 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61  e SQLite stack a
dfc0: 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69  re doing..** Thi
dfd0: 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  s file control i
dfe0: 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56  s used by some V
dff0: 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61 63  FS activity trac
e000: 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20  ing [shims]..** 
e010: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
e020: 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
e030: 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65  d string.  Highe
e040: 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a  r layers in the.
e050: 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  ** SQLite stack 
e060: 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73  may generate ins
e070: 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66  tances of this f
e080: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a  ile control if.*
e090: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  * the [SQLITE_US
e0a0: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63  E_FCNTL_TRACE] c
e0b0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
e0c0: 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a  on is enabled..*
e0d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
e0e0: 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45  E_FCNTL_HAS_MOVE
e0f0: 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  D]].** The [SQLI
e100: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
e110: 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ED] file control
e120: 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73 20   interprets its 
e130: 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a  argument as a.**
e140: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
e150: 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77 72  nteger and it wr
e160: 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69  ites a boolean i
e170: 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72  nto that integer
e180: 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e   depending.** on
e190: 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
e1a0: 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65 65  the file has bee
e1b0: 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64  n renamed, moved
e1c0: 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e  , or deleted sin
e1d0: 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72  ce it.** was fir
e1e0: 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a  st opened..**.**
e1f0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
e200: 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41  NTL_WIN32_SET_HA
e210: 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NDLE]].** The [S
e220: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
e230: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70  2_SET_HANDLE] op
e240: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
e250: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
e260: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
e270: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
e280: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77  rol method to sw
e290: 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64  ap the file hand
e2a0: 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a  le with the one.
e2b0: 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
e2c0: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
e2d0: 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62 69  nt.  This capabi
e2e0: 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75 72  lity is used dur
e2f0: 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61  ing testing.** a
e300: 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  nd only needs to
e310: 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68   be supported wh
e320: 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69  en SQLITE_TEST i
e330: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  s defined..**.**
e340: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
e350: 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a  NTL_WAL_BLOCK]].
e360: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
e370: 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20  CNTL_WAL_BLOCK] 
e380: 69 73 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74  is a signal to t
e390: 68 65 20 56 46 53 20 6c 61 79 65 72 20 74 68 61  he VFS layer tha
e3a0: 74 20 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65  t it might.** be
e3b0: 20 61 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f   advantageous to
e3c0: 20 62 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65   block on the ne
e3d0: 78 74 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74  xt WAL lock if t
e3e0: 68 65 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69  he lock is not i
e3f0: 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76  mmediately.** av
e400: 61 69 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41  ailable.  The WA
e410: 4c 20 73 75 62 73 79 73 74 65 6d 20 69 73 73 75  L subsystem issu
e420: 65 73 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64  es this signal d
e430: 75 72 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69  uring rare.** ci
e440: 72 63 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f  rcumstances in o
e450: 72 64 65 72 20 74 6f 20 66 69 78 20 61 20 70 72  rder to fix a pr
e460: 6f 62 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72  oblem with prior
e470: 69 74 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ity inversion..*
e480: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  * Applications s
e490: 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65  hould <em>not</e
e4a0: 6d 3e 20 75 73 65 20 74 68 69 73 20 66 69 6c 65  m> use this file
e4b0: 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  -control..**.** 
e4c0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
e4d0: 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54  TL_ZIPVFS]].** T
e4e0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
e4f0: 5f 5a 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20  _ZIPVFS] opcode 
e500: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62  is implemented b
e510: 79 20 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41  y zipvfs only. A
e520: 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20  ll other.** VFS 
e530: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51  should return SQ
e540: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f  LITE_NOTFOUND fo
e550: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a  r this opcode..*
e560: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
e570: 45 5f 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a  E_FCNTL_RBU]].**
e580: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
e590: 54 4c 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69  TL_RBU] opcode i
e5a0: 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79  s implemented by
e5b0: 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
e5c0: 20 75 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20   used by.** the 
e5d0: 52 42 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e  RBU extension on
e5e0: 6c 79 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56  ly.  All other V
e5f0: 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  FS should return
e600: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
e610: 20 66 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63   for.** this opc
e620: 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ode.  .** </ul>.
e630: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
e640: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
e650: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
e660: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
e670: 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50  _FCNTL_GET_LOCKP
e680: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 32  ROXYFILE       2
e690: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e6a0: 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52  FCNTL_SET_LOCKPR
e6b0: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a  OXYFILE       3.
e6c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
e6d0: 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  CNTL_LAST_ERRNO 
e6e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
e6f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
e700: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
e710: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
e720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
e730: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
e740: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
e750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
e760: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
e770: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
e780: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e790: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
e7a0: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
e7b0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
e7c0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
e7d0: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
e7e0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
e7f0: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
e800: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
e810: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
e820: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
e830: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
e840: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
e850: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
e860: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
e870: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
e880: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
e890: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
e8a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
e8b0: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
e8c0: 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    14.#define SQL
e8d0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
e8e0: 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20  NDLER           
e8f0: 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   15.#define SQLI
e900: 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c  TE_FCNTL_TEMPFIL
e910: 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  ENAME           
e920: 31 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  16.#define SQLIT
e930: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
e940: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
e950: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
e960: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20  _FCNTL_TRACE    
e970: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
e980: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e990: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20  FCNTL_HAS_MOVED 
e9a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 0a               20.
e9b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
e9c0: 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20  CNTL_SYNC       
e9d0: 20 20 20 20 20 20 20 20 20 20 20 20 32 31 0a 23              21.#
e9e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
e9f0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
ea00: 54 57 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64  TWO        22.#d
ea10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ea20: 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e  TL_WIN32_SET_HAN
ea30: 44 4c 45 20 20 20 20 20 20 20 32 33 0a 23 64 65  DLE       23.#de
ea40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ea50: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20  L_WAL_BLOCK     
ea60: 20 20 20 20 20 20 20 20 20 32 34 0a 23 64 65 66           24.#def
ea70: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ea80: 5f 5a 49 50 56 46 53 20 20 20 20 20 20 20 20 20  _ZIPVFS         
ea90: 20 20 20 20 20 20 20 20 32 35 0a 23 64 65 66 69          25.#defi
eaa0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
eab0: 52 42 55 20 20 20 20 20 20 20 20 20 20 20 20 20  RBU             
eac0: 20 20 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e         26.#defin
ead0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
eae0: 46 53 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  FS_POINTER      
eaf0: 20 20 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65        27.#define
eb00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f   SQLITE_FCNTL_JO
eb10: 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20  URNAL_POINTER   
eb20: 20 20 20 20 20 32 38 0a 0a 2f 2a 20 64 65 70 72       28../* depr
eb30: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a  ecated names */.
eb40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
eb50: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
eb60: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
eb70: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
eb80: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
eb90: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
eba0: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
ebb0: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
ebc0: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
ebd0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
ebe0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
ebf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
ec00: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20  T_ERRNO.../*.** 
ec10: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
ec20: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
ec30: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
ec40: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
ec50: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
ec60: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
ec70: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
ec80: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
ec90: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
eca0: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
ecb0: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
ecc0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
ecd0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
ece0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
ecf0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
ed00: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
ed10: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
ed20: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
ed30: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
ed40: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
ed50: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
ed60: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
ed70: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
ed80: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
ed90: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
eda0: 4c 6f 61 64 61 62 6c 65 20 45 78 74 65 6e 73 69  Loadable Extensi
edb0: 6f 6e 20 54 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41  on Thunk.**.** A
edc0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
edd0: 6f 70 61 71 75 65 20 73 71 6c 69 74 65 33 5f 61  opaque sqlite3_a
ede0: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 74 72 75  pi_routines stru
edf0: 63 74 75 72 65 20 69 73 20 70 61 73 73 65 64 20  cture is passed 
ee00: 61 73 0a 2a 2a 20 74 68 65 20 74 68 69 72 64 20  as.** the third 
ee10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 65 6e 74  parameter to ent
ee20: 72 79 20 70 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f  ry points of [lo
ee30: 61 64 61 62 6c 65 20 65 78 74 65 6e 73 69 6f 6e  adable extension
ee40: 73 5d 2e 20 20 54 68 69 73 0a 2a 2a 20 73 74 72  s].  This.** str
ee50: 75 63 74 75 72 65 20 6d 75 73 74 20 62 65 20 74  ucture must be t
ee60: 79 70 65 64 65 66 65 64 20 69 6e 20 6f 72 64 65  ypedefed in orde
ee70: 72 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  r to work around
ee80: 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69 6e   compiler warnin
ee90: 67 73 0a 2a 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c  gs.** on some pl
eea0: 61 74 66 6f 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65  atforms..*/.type
eeb0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
eec0: 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20  e3_api_routines 
eed0: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
eee0: 69 6e 65 73 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ines;../*.** CAP
eef0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
ef00: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
ef10: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
ef20: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
ef30: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
ef40: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
ef50: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
ef60: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
ef70: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
ef80: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
ef90: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
efa0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
efb0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
efc0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
efd0: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
efe0: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
eff0: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
f000: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
f010: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
f020: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
f030: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
f040: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
f050: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
f060: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
f070: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
f080: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
f090: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
f0a0: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
f0b0: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
f0c0: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
f0d0: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
f0e0: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
f0f0: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
f100: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
f110: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
f120: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
f130: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
f140: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
f150: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
f160: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
f170: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
f180: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
f190: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
f1a0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
f1b0: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
f1c0: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
f1d0: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
f1e0: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
f1f0: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
f200: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
f210: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
f220: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
f230: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
f240: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
f250: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
f260: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
f270: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
f280: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
f290: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
f2a0: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
f2b0: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
f2c0: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
f2d0: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
f2e0: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
f2f0: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
f300: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
f310: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
f320: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
f330: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
f340: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
f350: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
f360: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
f370: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
f380: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
f390: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
f3a0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
f3b0: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
f3c0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
f3d0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
f3e0: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
f3f0: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
f400: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
f410: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
f420: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
f430: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
f440: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
f450: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
f460: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
f470: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
f480: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
f490: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
f4a0: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
f4b0: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
f4c0: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
f4d0: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
f4e0: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
f4f0: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
f500: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
f510: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
f520: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
f530: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
f540: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
f550: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
f560: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
f570: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
f580: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
f590: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
f5a0: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
f5b0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
f5c0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
f5d0: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
f5e0: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
f5f0: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
f600: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
f610: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
f620: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
f630: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
f640: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
f650: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
f660: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
f670: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
f680: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
f690: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
f6a0: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
f6b0: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
f6c0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
f6d0: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
f6e0: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
f6f0: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
f700: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
f710: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
f720: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
f730: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
f740: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
f750: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
f760: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
f770: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
f780: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
f790: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
f7a0: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
f7b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
f7c0: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
f7d0: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
f7e0: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
f7f0: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
f800: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
f810: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
f820: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
f830: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
f840: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
f850: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
f860: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
f870: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
f880: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
f890: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
f8a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
f8b0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
f8c0: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
f8d0: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
f8e0: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
f8f0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
f900: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
f910: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
f920: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
f930: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
f940: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
f950: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
f960: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
f970: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
f980: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
f990: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
f9a0: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
f9b0: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
f9c0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
f9d0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
f9e0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
f9f0: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
fa00: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
fa10: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
fa20: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
fa30: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
fa40: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
fa50: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
fa60: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
fa70: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
fa80: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
fa90: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
faa0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
fab0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
fac0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
fad0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
fae0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
faf0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
fb00: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
fb10: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
fb20: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
fb30: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
fb40: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
fb50: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
fb60: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
fb70: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
fb80: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
fb90: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
fba0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
fbb0: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
fbc0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
fbd0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
fbe0: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
fbf0: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
fc00: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
fc10: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
fc20: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
fc30: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
fc40: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
fc50: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
fc60: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
fc70: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
fc80: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
fc90: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
fca0: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
fcb0: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
fcc0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
fcd0: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
fce0: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
fcf0: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
fd00: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
fd10: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
fd20: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
fd30: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
fd40: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
fd50: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
fd60: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
fd70: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
fd80: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
fd90: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
fda0: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
fdb0: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
fdc0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
fdd0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
fde0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
fdf0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
fe00: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
fe10: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
fe20: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
fe30: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
fe40: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
fe50: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
fe60: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
fe70: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
fe80: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
fe90: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
fea0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
feb0: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
fec0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
fed0: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
fee0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
fef0: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
ff00: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
ff10: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
ff20: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
ff30: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
ff40: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
ff50: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
ff60: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
ff70: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
ff80: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
ff90: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
ffa0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
ffb0: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
ffc0: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
ffd0: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
ffe0: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
fff0: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
10000 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
10010 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
10020 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
10030 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
10040 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
10050 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
10060 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
10070 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
10080 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
10090 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
100a0 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
100b0 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
100c0 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
100d0 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
100e0 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
100f0 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
10100 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
10110 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
10120 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
10130 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
10140 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
10150 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
10160 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
10170 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
10180 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
10190 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
101a0 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
101b0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
101c0 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
101d0 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
101e0 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
101f0 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
10200 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
10210 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
10220 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
10230 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
10240 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
10250 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
10260 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
10270 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
10280 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
10290 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
102a0 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
102b0 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
102c0 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
102d0 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
102e0 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
102f0 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
10300 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
10310 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
10320 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
10330 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
10340 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
10350 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
10360 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
10370 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
10380 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
10390 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
103a0 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
103b0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
103c0 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
103d0 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
103e0 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
103f0 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
10400 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
10410 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
10420 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
10430 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
10440 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
10450 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
10460 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
10470 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
10480 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
10490 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
104a0 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
104b0 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
104c0 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
104d0 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
104e0 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
104f0 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
10500 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
10510 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
10520 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
10530 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
10540 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
10550 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
10560 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
10570 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
10580 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
10590 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
105a0 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
105b0 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
105c0 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
105d0 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
105e0 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
105f0 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
10600 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
10610 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
10620 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
10630 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
10640 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
10650 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
10660 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
10670 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
10680 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
10690 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
106a0 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
106b0 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
106c0 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
106d0 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
106e0 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
106f0 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
10700 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
10710 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
10720 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
10730 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
10740 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
10750 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
10760 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
10770 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
10780 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
10790 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
107a0 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
107b0 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
107c0 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
107d0 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
107e0 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
107f0 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
10800 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
10810 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
10820 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
10830 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
10840 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
10850 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
10860 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
10870 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
10880 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
10890 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
108a0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
108b0 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
108c0 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
108d0 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
108e0 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
108f0 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
10900 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
10910 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
10920 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
10930 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
10940 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
10950 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
10960 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
10970 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
10980 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
10990 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
109a0 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
109b0 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
109c0 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
109d0 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
109e0 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
109f0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
10a00 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
10a10 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
10a20 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
10a30 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
10a40 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
10a50 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
10a60 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
10a70 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
10a80 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
10a90 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
10aa0 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
10ab0 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
10ac0 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
10ad0 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
10ae0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
10af0 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
10b00 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
10b10 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
10b20 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
10b30 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
10b40 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
10b50 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
10b60 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
10b70 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
10b80 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
10b90 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
10ba0 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
10bb0 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
10bc0 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
10bd0 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
10be0 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
10bf0 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
10c00 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
10c10 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
10c20 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
10c30 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
10c40 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
10c50 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
10c60 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
10c70 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
10c80 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
10c90 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
10ca0 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
10cb0 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
10cc0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
10cd0 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
10ce0 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
10cf0 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
10d00 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
10d10 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
10d20 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
10d30 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
10d40 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
10d50 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
10d60 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
10d70 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
10d80 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
10d90 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
10da0 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
10db0 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
10dc0 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
10dd0 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
10de0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
10df0 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
10e00 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
10e10 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
10e20 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
10e30 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
10e40 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
10e50 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
10e60 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
10e70 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
10e80 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
10e90 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
10ea0 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
10eb0 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
10ec0 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
10ed0 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
10ee0 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
10ef0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
10f00 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
10f10 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
10f20 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
10f30 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
10f40 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
10f50 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
10f60 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
10f70 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
10f80 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
10f90 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
10fa0 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
10fb0 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
10fc0 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
10fd0 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
10fe0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
10ff0 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
11000 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
11010 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
11020 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
11030 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
11040 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
11050 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
11060 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
11070 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
11080 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
11090 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
110a0 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
110b0 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
110c0 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
110d0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
110e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
110f0 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
11100 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
11110 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
11120 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
11130 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
11140 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
11150 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
11160 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
11170 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
11180 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
11190 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
111a0 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
111b0 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
111c0 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
111d0 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
111e0 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
111f0 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
11200 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
11210 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
11220 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
11230 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
11240 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
11250 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
11260 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
11270 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
11280 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
11290 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
112a0 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
112b0 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
112c0 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
112d0 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
112e0 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
112f0 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
11300 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
11310 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
11320 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
11330 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
11340 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
11350 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
11360 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
11370 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
11380 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
11390 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
113a0 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
113b0 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
113c0 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
113d0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
113e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
113f0 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
11400 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
11410 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
11420 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
11430 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
11440 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
11450 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
11460 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
11470 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
11480 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
11490 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
114a0 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
114b0 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
114c0 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
114d0 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
114e0 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
114f0 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
11500 70 65 6e 64 65 64 20 69 6e 20 66 75 74 75 72 65  pended in future
11510 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
11520 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
11530 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
11540 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
11550 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
11560 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
11570 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
11580 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
11590 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
115a0 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
115b0 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
115c0 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
115d0 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
115e0 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
115f0 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
11600 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
11610 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
11620 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
11630 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
11640 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
11650 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
11660 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
11670 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
11680 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
11690 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
116a0 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
116b0 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
116c0 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
116d0 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
116e0 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
116f0 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
11700 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
11710 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
11720 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
11730 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
11740 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
11750 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
11760 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
11770 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
11780 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
11790 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
117a0 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
117b0 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
117c0 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
117d0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
117e0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
117f0 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
11800 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
11810 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
11820 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
11830 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
11840 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
11850 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
11860 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
11870 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
11880 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
11890 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
118a0 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
118b0 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
118c0 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
118d0 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
118e0 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
118f0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
11900 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
11910 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
11920 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
11930 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
11940 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
11950 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
11960 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
11970 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
11980 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
11990 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
119a0 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
119b0 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
119c0 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
119d0 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
119e0 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
119f0 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
11a00 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
11a10 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
11a20 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
11a30 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
11a40 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
11a50 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
11a60 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
11a70 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
11a80 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
11a90 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
11aa0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
11ab0 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
11ac0 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
11ad0 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
11ae0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
11af0 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
11b00 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
11b10 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
11b20 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
11b30 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
11b40 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
11b50 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
11b60 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
11b70 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
11b80 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
11b90 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
11ba0 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
11bb0 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
11bc0 20 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68   was given on th
11bd0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
11be0 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
11bf0 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
11c00 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
11c10 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
11c20 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
11c30 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
11c40 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
11c50 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
11c60 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
11c70 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
11c80 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
11c90 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
11ca0 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
11cb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
11cc0 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
11cd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11ce0 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
11cf0 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
11d00 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
11d10 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
11d20 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
11d30 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
11d40 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
11d50 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
11d60 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
11d70 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
11d80 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
11d90 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
11da0 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
11db0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
11dc0 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
11dd0 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
11de0 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
11df0 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
11e00 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
11e10 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
11e20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
11e30 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
11e40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
11e50 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
11e60 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
11e70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
11e80 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
11e90 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
11ea0 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
11eb0 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
11ec0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
11ed0 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
11ee0 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
11ef0 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
11f00 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
11f10 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
11f20 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
11f30 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
11f40 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
11f50 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
11f60 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
11f70 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
11f80 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
11f90 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
11fa0 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
11fb0 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
11fc0 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
11fd0 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
11fe0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
11ff0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
12000 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
12010 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
12020 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
12030 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
12040 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12050 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
12060 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
12070 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
12080 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
12090 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
120a0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
120b0 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
120c0 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
120d0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
120e0 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
120f0 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
12100 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
12110 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12120 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
12130 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
12140 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
12150 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
12160 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
12170 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
12180 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
12190 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
121a0 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
121b0 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
121c0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
121d0 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
121e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
121f0 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
12200 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
12210 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
12220 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
12230 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
12240 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
12250 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
12260 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
12270 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
12280 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
12290 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
122a0 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
122b0 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
122c0 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
122d0 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
122e0 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
122f0 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
12300 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
12310 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
12320 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
12330 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
12340 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12350 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
12360 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
12370 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
12380 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
12390 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
123a0 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
123b0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
123c0 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
123d0 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
123e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
123f0 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
12400 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
12410 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
12420 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
12430 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
12440 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
12450 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
12460 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12470 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
12480 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
12490 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
124a0 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
124b0 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
124c0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
124d0 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
124e0 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
124f0 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
12500 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
12510 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
12520 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
12530 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
12540 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
12550 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
12560 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
12570 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
12580 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
12590 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
125a0 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
125b0 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
125c0 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
125d0 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
125e0 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
125f0 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
12600 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
12610 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
12620 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
12630 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
12640 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
12650 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12660 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
12670 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
12680 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
12690 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
126a0 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
126b0 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
126c0 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
126d0 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
126e0 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
126f0 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
12700 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
12710 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
12720 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
12730 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
12740 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
12750 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
12760 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
12770 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
12780 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
12790 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
127a0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
127b0 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
127c0 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
127d0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
127e0 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
127f0 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
12800 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
12810 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
12820 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
12830 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
12840 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
12850 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
12860 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
12870 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
12880 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
12890 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
128a0 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
128b0 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
128c0 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
128d0 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
128e0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
128f0 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
12900 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
12910 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
12920 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
12930 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
12940 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
12950 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
12960 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
12970 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
12980 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
12990 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
129a0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
129b0 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
129c0 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
129d0 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
129e0 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
129f0 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
12a00 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
12a10 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
12a20 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
12a30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
12a40 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
12a50 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
12a60 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
12a70 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
12a80 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
12a90 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
12aa0 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
12ab0 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
12ac0 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
12ad0 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
12ae0 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
12af0 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
12b00 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
12b10 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
12b20 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
12b30 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
12b40 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
12b50 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
12b60 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
12b70 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
12b80 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
12b90 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
12ba0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
12bb0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
12bc0 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
12bd0 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
12be0 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
12bf0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
12c00 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
12c10 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
12c20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
12c30 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
12c40 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12c50 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
12c60 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
12c70 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
12c80 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
12c90 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
12ca0 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
12cb0 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
12cc0 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
12cd0 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
12ce0 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
12cf0 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
12d00 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
12d10 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
12d20 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
12d30 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
12d40 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
12d50 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
12d60 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
12d70 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
12d80 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
12d90 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
12da0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
12db0 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
12dc0 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
12dd0 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
12de0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
12df0 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
12e00 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
12e10 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
12e20 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
12e30 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
12e40 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
12e50 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
12e60 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
12e70 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
12e80 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49  lize(void);.SQLI
12e90 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
12ea0 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
12eb0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
12ec0 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
12ed0 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  t(void);.SQLITE_
12ee0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
12ef0 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
12f00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
12f10 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
12f20 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
12f30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12f40 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
12f50 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
12f60 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
12f70 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
12f80 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
12f90 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
12fa0 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
12fb0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
12fc0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
12fd0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
12fe0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
12ff0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
13000 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
13010 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
13020 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
13030 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
13040 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
13050 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
13060 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
13070 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
13080 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  needs..**.** <b>
13090 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
130a0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
130b0 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
130c0 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
130d0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
130e0 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
130f0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
13100 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
13110 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
13120 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
13130 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
13140 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68  ng.</b>.**.** Th
13150 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
13160 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
13170 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
13180 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
13190 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
131a0 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
131b0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
131c0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
131d0 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
131e0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
131f0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
13200 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
13210 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
13220 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
13230 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
13240 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
13250 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
13260 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
13270 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
13280 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
13290 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
132a0 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
132b0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
132c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
132d0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
132e0 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
132f0 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
13300 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
13310 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
13320 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
13330 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
13340 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
13350 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
13360 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
13370 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
13380 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
13390 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
133a0 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
133b0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
133c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
133d0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
133e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
133f0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
13400 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13410 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
13420 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
13430 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
13440 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
13450 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
13460 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
13470 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
13480 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
13490 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
134a0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
134b0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c  or code]..*/.SQL
134c0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
134d0 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
134e0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
134f0 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
13500 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13510 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
13520 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
13530 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  he sqlite3_db_co
13540 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
13550 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
13560 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
13570 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b  * changes to a [
13580 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13590 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72  ion].  The inter
135a0 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20  face is similar 
135b0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
135c0 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20  onfig()] except 
135d0 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73  that the changes
135e0 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67   apply to a sing
135f0 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  le.** [database 
13600 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65  connection] (spe
13610 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69  cified in the fi
13620 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a  rst argument)..*
13630 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
13640 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
13650 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c  te3_db_config(D,
13660 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a  V,...)  is the.*
13670 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  * [SQLITE_DBCONF
13680 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63  IG_LOOKASIDE | c
13690 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
136a0 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20  b] - an integer 
136b0 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e  code .** that in
136c0 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70  dicates what asp
136d0 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ect of the [data
136e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
136f0 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67   is being config
13700 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75  ured..** Subsequ
13710 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61  ent arguments va
13720 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ry depending on 
13730 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
13740 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43  n verb..**.** ^C
13750 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
13760 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  db_config() retu
13770 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20  rn SQLITE_OK if 
13780 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74  and only if.** t
13790 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69  he call is consi
137a0 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c  dered successful
137b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
137c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  int sqlite3_db_c
137d0 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20  onfig(sqlite3*, 
137e0 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f  int op, ...);../
137f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
13800 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
13810 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20   Routines.**.** 
13820 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
13830 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e  his object defin
13840 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
13850 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a   between SQLite.
13860 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c  ** and low-level
13870 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
13880 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  on routines..**.
13890 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
138a0 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f  s used in only o
138b0 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20  ne place in the 
138c0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
138d0 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74  ..** A pointer t
138e0 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
138f0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   this object is 
13900 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  the argument to.
13910 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
13920 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63  ig()] when the c
13930 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13940 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54  ion is.** [SQLIT
13950 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
13960 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
13970 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20  IG_GETMALLOC].  
13980 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20  .** By creating 
13990 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
139a0 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  his object.** an
139b0 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20  d passing it to 
139c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
139d0 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
139e0 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69  MALLOC]).** duri
139f0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
13a00 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
13a10 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20   can specify an 
13a20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d  alternative.** m
13a30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13a40 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53   subsystem for S
13a50 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72  QLite to use for
13a60 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64   all of its.** d
13a70 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65  ynamic memory ne
13a80 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  eds..**.** Note 
13a90 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65  that SQLite come
13aa0 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b  s with several [
13ab0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
13ac0 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74  allocators].** t
13ad0 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c  hat are perfectl
13ae0 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74  y adequate for t
13af0 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20  he overwhelming 
13b00 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  majority of appl
13b10 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20  ications.** and 
13b20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74  that this object
13b30 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20   is only useful 
13b40 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69  to a tiny minori
13b50 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
13b60 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69  ns.** with speci
13b70 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c  alized memory al
13b80 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65  location require
13b90 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a  ments.  This obj
13ba0 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75  ect is.** also u
13bb0 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
13bc0 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20  ng of SQLite in 
13bd0 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79  order to specify
13be0 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
13bf0 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
13c00 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  tor that simulat
13c10 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66  es memory out-of
13c20 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f  -memory conditio
13c30 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74  ns in.** order t
13c40 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51  o verify that SQ
13c50 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72  Lite recovers gr
13c60 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75  acefully from su
13c70 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73  ch.** conditions
13c80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c  ..**.** The xMal
13c90 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61  loc, xRealloc, a
13ca0 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73  nd xFree methods
13cb0 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20   must work like 
13cc0 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c  the.** malloc(),
13cd0 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66   realloc() and f
13ce0 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20  ree() functions 
13cf0 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
13d00 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
13d10 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
13d20 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f  es that the seco
13d30 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
13d40 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c  * xRealloc is al
13d50 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74  ways a value ret
13d60 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72  urned by a prior
13d70 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75   call to xRoundu
13d80 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73  p..**.** xSize s
13d90 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  hould return the
13da0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
13db0 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  of a memory allo
13dc0 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f  cation.** previo
13dd0 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72  usly obtained fr
13de0 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52  om xMalloc or xR
13df0 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c  ealloc.  The all
13e00 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69  ocated size.** i
13e10 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73  s always at leas
13e20 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20  t as big as the 
13e30 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62  requested size b
13e40 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
13e50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75  ..**.** The xRou
13e60 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75  ndup method retu
13e70 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62  rns what would b
13e80 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  e the allocated 
13e90 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d  size of.** a mem
13ea0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67  ory allocation g
13eb0 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61  iven a particula
13ec0 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65  r requested size
13ed0 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a  .  Most memory.*
13ee0 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75  * allocators rou
13ef0 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c  nd up memory all
13f00 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73  ocations at leas
13f10 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75  t to the next mu
13f20 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20  ltiple.** of 8. 
13f30 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73   Some allocators
13f40 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c   round up to a l
13f50 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  arger multiple o
13f60 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20  r to a power of 
13f70 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f  2..** Every memo
13f80 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65  ry allocation re
13f90 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20  quest coming in 
13fa0 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33  through [sqlite3
13fb0 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72  _malloc()].** or
13fc0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
13fd0 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73  c()] first calls
13fe0 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78   xRoundup.  If x
13ff0 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20  Roundup returns 
14000 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73  0, .** that caus
14010 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  es the correspon
14020 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ding memory allo
14030 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a  cation to fail..
14040 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20  **.** The xInit 
14050 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a  method initializ
14060 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
14070 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78  locator.  For ex
14080 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
14090 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
140a0 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
140b0 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
140c0 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
140d0 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
140e0 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
140f0 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
14100 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
14110 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
14120 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
14130 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
14140 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
14150 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
14160 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
14170 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
14180 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
14190 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
141a0 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
141b0 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
141c0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
141d0 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
141e0 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
141f0 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
14200 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
14210 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
14220 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
14230 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
14240 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
14250 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
14260 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
14270 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
14280 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
14290 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
142a0 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
142b0 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
142c0 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
142d0 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
142e0 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
142f0 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
14300 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
14310 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
14320 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
14330 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
14340 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
14350 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
14360 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
14370 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
14380 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
14390 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
143a0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
143b0 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
143c0 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
143d0 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
143e0 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
143f0 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
14400 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
14410 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
14420 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
14430 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
14440 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
14450 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
14460 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
14470 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
14480 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
14490 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
144a0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
144b0 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
144c0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
144d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
144e0 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
144f0 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
14500 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
14510 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14520 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
14530 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
14540 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
14550 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
14560 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
14570 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
14580 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
14590 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
145a0 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
145b0 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
145c0 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
145d0 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
145e0 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
145f0 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
14600 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
14610 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
14620 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
14630 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
14640 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
14650 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
14660 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
14670 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
14680 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
14690 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
146a0 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
146b0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
146c0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
146d0 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
146e0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
146f0 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
14700 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
14710 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
14720 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
14730 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
14740 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
14750 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
14760 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
14770 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
14780 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
14790 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
147a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
147b0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
147c0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
147d0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
147e0 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
147f0 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
14800 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
14810 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
14820 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
14830 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
14840 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
14850 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
14860 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
14870 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
14880 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
14890 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
148a0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
148b0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
148c0 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
148d0 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
148e0 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
148f0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
14900 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
14910 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
14920 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
14930 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
14940 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
14950 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
14960 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
14970 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
14980 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
14990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
149a0 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
149b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
149c0 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
149d0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
149e0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
149f0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
14a00 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
14a10 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
14a20 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
14a30 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
14a40 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
14a50 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
14a60 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
14a70 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
14a80 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
14a90 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
14aa0 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
14ab0 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
14ac0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
14ad0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
14ae0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
14af0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
14b00 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
14b10 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
14b20 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
14b30 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
14b40 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
14b50 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
14b60 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
14b70 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
14b80 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
14b90 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
14ba0 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
14bb0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
14bc0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
14bd0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
14be0 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
14bf0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
14c00 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14c10 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
14c20 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
14c30 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
14c40 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
14c50 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
14c60 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
14c70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
14c80 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
14c90 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
14ca0 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
14cb0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
14cc0 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
14cd0 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
14ce0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14cf0 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
14d00 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
14d10 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
14d20 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
14d30 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
14d40 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
14d50 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
14d60 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
14d70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
14d80 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
14d90 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
14da0 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
14db0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
14dc0 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
14dd0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
14de0 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
14df0 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
14e00 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
14e10 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
14e20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
14e30 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
14e40 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
14e50 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14e60 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
14e70 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
14e80 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
14e90 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
14ea0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
14eb0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
14ec0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
14ed0 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
14ee0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
14ef0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
14f00 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
14f10 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
14f20 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
14f30 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
14f40 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
14f50 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
14f60 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
14f70 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
14f80 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
14f90 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
14fa0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
14fb0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
14fc0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
14fd0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
14fe0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
14ff0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
15000 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
15010 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
15020 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
15030 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
15040 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
15050 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
15060 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
15070 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
15080 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
15090 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
150a0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
150b0 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
150c0 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
150d0 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
150e0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
150f0 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
15100 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
15110 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
15120 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
15130 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
15140 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
15150 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
15160 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
15170 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
15180 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
15190 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
151a0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
151b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
151c0 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
151d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
151e0 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
151f0 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
15200 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
15210 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
15220 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
15230 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
15240 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
15250 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
15260 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
15270 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
15280 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
15290 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
152a0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
152b0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
152c0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
152d0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
152e0 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
152f0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
15300 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
15310 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
15320 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
15330 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15340 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
15350 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
15360 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
15370 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
15380 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 6f 70 74  ONFIG_MALLOC opt
15390 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
153a0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
153b0 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  h is .** a point
153c0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
153d0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
153e0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
153f0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
15400 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
15410 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
15420 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
15430 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
15440 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
15450 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
15460 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
15470 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
15480 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
15490 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
154a0 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
154b0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
154c0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
154d0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
154e0 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
154f0 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
15500 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
15510 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
15520 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15530 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15540 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
15550 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
15560 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
15570 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   ^(The SQLITE_CO
15580 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 6f  NFIG_GETMALLOC o
15590 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
155a0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
155b0 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
155c0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
155d0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
155e0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
155f0 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
15600 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
15610 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
15620 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
15630 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
15640 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
15650 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
15660 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
15670 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
15680 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
15690 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
156a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
156b0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
156c0 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
156d0 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
156e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
156f0 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
15700 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
15710 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
15720 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15730 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
15740 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15750 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
15760 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
15770 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15780 45 4d 53 54 41 54 55 53 20 6f 70 74 69 6f 6e 20  EMSTATUS option 
15790 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
157a0 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
157b0 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 65  t,.** interprete
157c0 64 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 2c 20  d as a boolean, 
157d0 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
157e0 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
157f0 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a 2a 20 6d  llection of.** m
15800 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15810 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57   statistics. ^(W
15820 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hen memory alloc
15830 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
15840 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64   are.** disabled
15850 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  , the following 
15860 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
15870 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
15880 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
15890 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
158a0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
158b0 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
158c0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
158d0 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
158e0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
158f0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
15900 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
15910 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 36 34  sqlite3_status64
15920 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
15930 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
15940 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
15950 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
15960 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
15970 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
15980 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
15990 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
159a0 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
159b0 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
159c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
159d0 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
159e0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
159f0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
15a00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
15a10 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
15a20 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
15a30 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
15a40 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
15a50 47 5f 53 43 52 41 54 43 48 20 6f 70 74 69 6f 6e  G_SCRATCH option
15a60 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
15a70 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
15a80 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  r.** that SQLite
15a90 20 63 61 6e 20 75 73 65 20 66 6f 72 20 73 63 72   can use for scr
15aa0 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 5e 28  atch memory.  ^(
15ab0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
15ac0 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 74 6f 20  arguments.** to 
15ad0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
15ae0 52 41 54 43 48 3a 20 20 41 20 70 6f 69 6e 74 65  RATCH:  A pointe
15af0 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
15b00 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
15b10 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
15b20 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
15b30 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
15b40 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
15b50 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
15b60 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
15b70 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
15b80 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
15b90 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
15ba0 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a 2a 20 54  ions (N).)^.** T
15bb0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15bc0 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e  t must be a poin
15bd0 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
15be0 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a   aligned buffer.
15bf0 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  ** of at least s
15c00 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
15c10 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
15c20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20 6d 6f 72  will not use mor
15c30 65 20 74 68 61 6e 20 6f 6e 65 20 73 63 72 61 74  e than one scrat
15c40 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20 74  ch buffers per t
15c50 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51 4c 69 74  hread..** ^SQLit
15c60 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
15c70 75 65 73 74 20 61 20 73 63 72 61 74 63 68 20 62  uest a scratch b
15c80 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
15c90 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
15ca0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
15cb0 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49  page size..** ^I
15cc0 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
15cd0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
15ce0 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
15cf0 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
15d00 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
15d10 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
15d20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
15d30 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15d40 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
15d50 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
15d60 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 70 3e  emory needed.<p>
15d70 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 61 70  .** ^When the ap
15d80 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 76 69 64  plication provid
15d90 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74 20 6f 66  es any amount of
15da0 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
15db0 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49 54 45 5f  using.** SQLITE_
15dc0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 2c 20  CONFIG_SCRATCH, 
15dd0 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20 75 6e  SQLite avoids un
15de0 6e 65 63 65 73 73 61 72 79 20 6c 61 72 67 65 0a  necessary large.
15df0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
15e00 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63 61 74 69  oc|heap allocati
15e10 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73 20 63 61  ons]..** This ca
15e20 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f 6e 20 70  n help [Robson p
15e30 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20 6d 65 6d  roof|prevent mem
15e40 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
15e50 61 69 6c 75 72 65 73 5d 20 64 75 65 20 74 6f 20  ailures] due to 
15e60 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d 65 6e 74  heap.** fragment
15e70 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d 6d 65 6d  ation in low-mem
15e80 6f 72 79 20 65 6d 62 65 64 64 65 64 20 73 79 73  ory embedded sys
15e90 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  tems..** </dd>.*
15ea0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15eb0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d  NFIG_PAGECACHE]]
15ec0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15ed0 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
15ee0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53  >.** <dd> ^The S
15ef0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
15f00 45 43 41 43 48 45 20 6f 70 74 69 6f 6e 20 73 70  ECACHE option sp
15f10 65 63 69 66 69 65 73 20 61 20 6d 65 6d 6f 72 79  ecifies a memory
15f20 20 70 6f 6f 6c 0a 2a 2a 20 74 68 61 74 20 53 51   pool.** that SQ
15f30 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
15f40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
15f50 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
15f60 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 0a 2a  e default page.*
15f70 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
15f80 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69  tation.  .** Thi
15f90 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
15fa0 6f 70 74 69 6f 6e 20 69 73 20 61 20 6e 6f 2d 6f  option is a no-o
15fb0 70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  p if an applicat
15fc0 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
15fd0 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
15fe0 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
15ff0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c  d using the [SQL
16000 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
16010 45 32 5d 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61  E2]..** ^There a
16020 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
16030 74 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  ts to SQLITE_CON
16040 46 49 47 5f 50 41 47 45 43 41 43 48 45 3a 20 41  FIG_PAGECACHE: A
16050 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 38   pointer to.** 8
16060 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 6d 65  -byte aligned me
16070 6d 6f 72 79 20 28 70 4d 65 6d 29 2c 20 74 68 65  mory (pMem), the
16080 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
16090 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20 28 73  ge cache line (s
160a0 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6e  z),.** and the n
160b0 75 6d 62 65 72 20 6f 66 20 63 61 63 68 65 20 6c  umber of cache l
160c0 69 6e 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ines (N)..** The
160d0 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
160e0 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
160f0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
16100 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
16110 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
16120 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
16130 36 35 35 33 36 29 20 70 6c 75 73 20 73 6f 6d 65  65536) plus some
16140 20 65 78 74 72 61 20 62 79 74 65 73 20 66 6f 72   extra bytes for
16150 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65   each.** page he
16160 61 64 65 72 2e 20 20 5e 54 68 65 20 6e 75 6d 62  ader.  ^The numb
16170 65 72 20 6f 66 20 65 78 74 72 61 20 62 79 74 65  er of extra byte
16180 73 20 6e 65 65 64 65 64 20 62 79 20 74 68 65 20  s needed by the 
16190 70 61 67 65 20 68 65 61 64 65 72 0a 2a 2a 20 63  page header.** c
161a0 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
161b0 20 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43   using [SQLITE_C
161c0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52  ONFIG_PCACHE_HDR
161d0 53 5a 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68  SZ]..** ^It is h
161e0 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
161f0 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
16200 65 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68  emory,.** for th
16210 65 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74  e sz parameter t
16220 6f 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  o be larger than
16230 20 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65   necessary.  The
16240 20 70 4d 65 6d 0a 2a 2a 20 61 72 67 75 6d 65 6e   pMem.** argumen
16250 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
16260 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
16270 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  or a pointer to 
16280 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
16290 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  gned block of me
162a0 6d 6f 72 79 20 6f 66 20 61 74 20 6c 65 61 73 74  mory of at least
162b0 20 73 7a 2a 4e 20 62 79 74 65 73 2c 20 6f 74 68   sz*N bytes, oth
162c0 65 72 77 69 73 65 0a 2a 2a 20 73 75 62 73 65 71  erwise.** subseq
162d0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73  uent behavior is
162e0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
162f0 57 68 65 6e 20 70 4d 65 6d 20 69 73 20 6e 6f 74  When pMem is not
16300 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69   NULL, SQLite wi
16310 6c 6c 20 73 74 72 69 76 65 20 74 6f 20 75 73 65  ll strive to use
16320 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
16330 69 64 65 64 0a 2a 2a 20 74 6f 20 73 61 74 69 73  ided.** to satis
16340 66 79 20 70 61 67 65 20 63 61 63 68 65 20 6e 65  fy page cache ne
16350 65 64 73 2c 20 66 61 6c 6c 69 6e 67 20 62 61 63  eds, falling bac
16360 6b 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  k to [sqlite3_ma
16370 6c 6c 6f 63 28 29 5d 20 69 66 0a 2a 2a 20 61 20  lloc()] if.** a 
16380 70 61 67 65 20 63 61 63 68 65 20 6c 69 6e 65 20  page cache line 
16390 69 73 20 6c 61 72 67 65 72 20 74 68 61 6e 20 73  is larger than s
163a0 7a 20 62 79 74 65 73 20 6f 72 20 69 66 20 61 6c  z bytes or if al
163b0 6c 20 6f 66 20 74 68 65 20 70 4d 65 6d 20 62 75  l of the pMem bu
163c0 66 66 65 72 0a 2a 2a 20 69 73 20 65 78 68 61 75  ffer.** is exhau
163d0 73 74 65 64 2e 0a 2a 2a 20 5e 49 66 20 70 4d 65  sted..** ^If pMe
163e0 6d 20 69 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20  m is NULL and N 
163f0 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  is non-zero, the
16400 6e 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  n each database 
16410 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 64 6f  connection.** do
16420 65 73 20 61 6e 20 69 6e 69 74 69 61 6c 20 62 75  es an initial bu
16430 6c 6b 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  lk allocation fo
16440 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
16450 6f 72 79 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ory.** from [sql
16460 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73  ite3_malloc()] s
16470 75 66 66 69 63 69 65 6e 74 20 66 6f 72 20 4e 20  ufficient for N 
16480 63 61 63 68 65 20 6c 69 6e 65 73 20 69 66 20 4e  cache lines if N
16490 20 69 73 20 70 6f 73 69 74 69 76 65 20 6f 72 0a   is positive or.
164a0 2a 2a 20 6f 66 20 2d 31 30 32 34 2a 4e 20 62 79  ** of -1024*N by
164b0 74 65 73 20 69 66 20 4e 20 69 73 20 6e 65 67 61  tes if N is nega
164c0 74 69 76 65 2c 20 2e 20 5e 49 66 20 61 64 64 69  tive, . ^If addi
164d0 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
164e0 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
164f0 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
16500 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
16510 20 74 68 65 20 69 6e 69 74 69 61 6c 0a 2a 2a 20   the initial.** 
16520 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
16530 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
16540 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
16550 29 5d 20 73 65 70 61 72 61 74 65 6c 79 20 66 6f  )] separately fo
16560 72 20 65 61 63 68 0a 2a 2a 20 61 64 64 69 74 69  r each.** additi
16570 6f 6e 61 6c 20 63 61 63 68 65 20 6c 69 6e 65 2e  onal cache line.
16580 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
16590 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
165a0 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
165b0 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
165c0 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
165d0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
165e0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
165f0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
16600 20 62 75 66 66 65 72 20 0a 2a 2a 20 74 68 61 74   buffer .** that
16610 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
16620 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
16630 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
16640 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 0a  llocation needs.
16650 2a 2a 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ** beyond those 
16660 70 72 6f 76 69 64 65 64 20 66 6f 72 20 62 79 20  provided for by 
16670 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
16680 43 52 41 54 43 48 5d 20 61 6e 64 0a 2a 2a 20 5b  CRATCH] and.** [
16690 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
166a0 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 5e 54 68  GECACHE]..** ^Th
166b0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
166c0 48 45 41 50 20 6f 70 74 69 6f 6e 20 69 73 20 6f  HEAP option is o
166d0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
166e0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
166f0 6c 65 64 0a 2a 2a 20 77 69 74 68 20 65 69 74 68  led.** with eith
16700 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
16710 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 20 5b 53  E_MEMSYS3] or [S
16720 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
16730 53 59 53 35 5d 20 61 6e 64 20 72 65 74 75 72 6e  SYS5] and return
16740 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52  s.** [SQLITE_ERR
16750 4f 52 5d 20 69 66 20 69 6e 76 6f 6b 65 64 20 6f  OR] if invoked o
16760 74 68 65 72 77 69 73 65 2e 0a 2a 2a 20 5e 54 68  therwise..** ^Th
16770 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
16780 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
16790 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3a 0a 2a  E_CONFIG_HEAP:.*
167a0 2a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  * An 8-byte alig
167b0 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
167c0 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
167d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
167e0 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
167f0 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
16800 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
16810 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
16820 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
16830 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
16840 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
16850 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
16860 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
16870 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
16880 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
16890 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
168a0 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
168b0 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
168c0 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
168d0 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
168e0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
168f0 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
16900 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
16910 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 61 6c  NULL then the al
16920 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79  ternative memory
16930 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73  .** allocator is
16940 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64   engaged to hand
16950 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65  le all of SQLite
16960 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
16970 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68  ion needs..** Th
16980 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
16990 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
169a0 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69  ter) must be ali
169b0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
169c0 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72  e.** boundary or
169d0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
169e0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77  vior of SQLite w
169f0 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
16a00 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d  ..** The minimum
16a10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
16a20 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a   is capped at 2*
16a30 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20  *12. Reasonable 
16a40 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68  values.** for th
16a50 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
16a60 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a  tion size are 2*
16a70 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e  *5 through 2**8.
16a80 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
16aa0 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
16ab0 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e  ONFIG_MUTEX</dt>
16ac0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
16ad0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
16ae0 45 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  EX option takes 
16af0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
16b00 74 20 77 68 69 63 68 20 69 73 20 61 0a 2a 2a 20  t which is a.** 
16b10 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
16b20 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
16b30 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
16b40 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
16b50 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
16b60 20 73 70 65 63 69 66 69 65 73 20 61 6c 74 65 72   specifies alter
16b70 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
16b80 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
16b90 74 6f 20 62 65 20 75 73 65 64 0a 2a 2a 20 69 6e  to be used.** in
16ba0 20 70 6c 61 63 65 20 74 68 65 20 6d 75 74 65 78   place the mutex
16bb0 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
16bc0 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
16bd0 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
16be0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
16bf0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
16c00 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
16c10 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
16c20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
16c30 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
16c40 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
16c50 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
16c60 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
16c70 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
16c80 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
16c90 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
16ca0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16cb0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
16cc0 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
16cd0 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
16ce0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
16cf0 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
16d00 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
16d10 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
16d20 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
16d30 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
16d40 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
16d50 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
16d60 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
16d70 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16d80 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
16d90 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16da0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
16db0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
16dc0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
16dd0 45 54 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74  ETMUTEX option t
16de0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
16df0 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
16e00 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
16e10 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
16e20 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
16e30 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  x_methods] struc
16e40 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73  ture.  The.** [s
16e50 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
16e60 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75  hods].** structu
16e70 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  re is filled wit
16e80 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20  h the currently 
16e90 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f  defined mutex ro
16ea0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
16eb0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
16ec0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
16ed0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74   the default mut
16ee0 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ex allocation.**
16ef0 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
16f00 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74 6f   wrapper used to
16f10 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61   track mutex usa
16f20 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e  ge for performan
16f30 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20  ce.** profiling 
16f40 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20  or testing, for 
16f50 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53  example.   ^If S
16f60 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
16f70 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
16f80 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
16f90 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
16fa0 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
16fb0 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
16fc0 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
16fd0 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
16fe0 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
16ff0 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
17000 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
17010 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
17020 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
17030 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
17040 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
17050 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
17060 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
17070 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
17080 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17090 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20  FIG_LOOKASIDE]] 
170a0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
170b0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
170c0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
170d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
170e0 4b 41 53 49 44 45 20 6f 70 74 69 6f 6e 20 74 61  KASIDE option ta
170f0 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
17100 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
17110 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 20  .** the default 
17120 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b 61 73 69 64  size of lookasid
17130 65 20 6d 65 6d 6f 72 79 20 6f 6e 20 65 61 63 68  e memory on each
17140 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
17150 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 66  ction]..** The f
17160 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
17170 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
17180 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
17190 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
171a0 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
171b0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
171c0 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
171d0 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
171e0 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
171f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
17200 4f 4b 41 53 49 44 45 0a 2a 2a 20 73 65 74 73 20  OKASIDE.** sets 
17210 74 68 65 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  the <i>default</
17220 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
17230 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
17240 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
17250 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e 20 74 6f 20  E].** option to 
17260 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
17270 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65  ig()] can be use
17280 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
17290 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e  lookaside.** con
172a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e  figuration on in
172b0 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74  dividual connect
172c0 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ions.)^ </dd>.**
172d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
172e0 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64  FIG_PCACHE2]] <d
172f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17300 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
17310 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
17320 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
17330 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17340 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
17350 77 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70  which is .** a p
17360 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
17370 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
17380 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
17390 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
173a0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 69 6e 74  ifies.** the int
173b0 65 72 66 61 63 65 20 74 6f 20 61 20 63 75 73 74  erface to a cust
173c0 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
173d0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 0a  plementation.)^.
173e0 2a 2a 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ** ^SQLite makes
173f0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
17400 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
17410 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
17420 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
17430 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
17440 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
17450 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
17460 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
17470 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
17480 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
17490 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  2 option takes a
174a0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
174b0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
174c0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 5b 73 71  ointer to an [sq
174d0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
174e0 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
174f0 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
17500 0a 2a 2a 20 74 68 65 20 63 75 72 72 65 6e 74 20  .** the current 
17510 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
17520 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
17530 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
17540 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
17550 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
17560 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17570 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
17580 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
17590 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
175a0 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
175b0 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
175c0 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
175d0 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
175e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
175f0 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
17600 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
17610 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
17620 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
17630 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
17640 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
17650 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
17660 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
17670 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
17680 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
17690 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
176a0 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
176b0 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
176c0 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
176d0 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
176e0 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
176f0 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
17700 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
17710 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
17720 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
17730 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
17740 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
17750 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
17760 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
17770 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
17780 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
17790 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
177a0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
177b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
177c0 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
177d0 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
177e0 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
177f0 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
17800 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17810 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
17820 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
17830 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
17840 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
17850 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
17860 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
17870 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
17880 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
17890 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
178a0 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
178b0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
178c0 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
178d0 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
178e0 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
178f0 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
17900 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
17910 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
17920 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
17930 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
17940 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
17950 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
17960 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
17970 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
17980 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
17990 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
179a0 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
179b0 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
179c0 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
179d0 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
179e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
179f0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
17a00 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
17a10 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
17a20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
17a30 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
17a40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
17a50 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 65 20 53  I.** <dd>^(The S
17a60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
17a70 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17a80 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
17a90 6f 66 20 74 79 70 65 20 69 6e 74 2e 0a 2a 2a 20  of type int..** 
17aa0 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
17ab0 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  n URI handling i
17ac0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
17ad0 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
17ae0 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a  eter is zero,.**
17af0 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
17b00 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ng is globally d
17b10 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55  isabled.)^ ^If U
17b20 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
17b30 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65 6e 61 62 6c  lobally.** enabl
17b40 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
17b50 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
17b60 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
17b70 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
17b80 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  ],.** [sqlite3_o
17b90 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
17ba0 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
17bb0 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
17bc0 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
17bd0 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
17be0 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
17bf0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
17c00 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
17c10 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
17c20 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
17c30 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
17c40 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20   is opened. ^If 
17c50 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
17c60 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
17c70 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
17c80 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
17c90 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
17ca0 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
17cb0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
17cc0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
17cd0 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
17ce0 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55   ^(By default, U
17cf0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
17d00 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
17d10 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
17d20 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
17d30 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
17d40 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
17d50 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
17d60 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29  symbol defined.)
17d70 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
17d80 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
17d90 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64  _INDEX_SCAN]] <d
17da0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17db0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
17dc0 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  CAN.** <dd>^The 
17dd0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
17de0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
17df0 4e 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  N option takes a
17e00 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 0a   single integer.
17e10 2a 2a 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  ** argument whic
17e20 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
17e30 20 61 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e   as a boolean in
17e40 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
17e50 20 6f 72 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   or disable.** t
17e60 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
17e70 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
17e80 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
17e90 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
17ea0 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  imizer..** ^The 
17eb0 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
17ec0 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a  is determined.**
17ed0 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   by the [SQLITE_
17ee0 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49  ALLOW_COVERING_I
17ef0 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69  NDEX_SCAN] compi
17f00 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20  le-time option, 
17f10 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66  or is "on".** if
17f20 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69   that compile-ti
17f30 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69  me option is omi
17f40 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69  tted..** The abi
17f50 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20  lity to disable 
17f60 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
17f70 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20  ing indices for 
17f80 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
17f90 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73  .** is because s
17fa0 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  ome incorrectly 
17fb0 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70  coded legacy app
17fc0 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  lications might 
17fd0 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77  malfunction.** w
17fe0 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
17ff0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
18000 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
18010 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
18020 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
18030 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
18040 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
18050 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
18060 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
18070 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
18080 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
18090 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
180a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
180b0 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
180c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
180d0 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
180e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
180f0 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
18100 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
18110 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
18120 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
18130 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
18140 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
18150 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
18160 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
18170 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
18180 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
18190 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
181a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
181b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
181c0 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
181d0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
181e0 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
181f0 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
18200 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
18210 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
18220 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
18230 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70  ENABLE_SQLLOG] p
18240 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
18250 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20  ro defined. The 
18260 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73  first argument s
18270 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f  hould.** be a po
18280 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74  inter to a funct
18290 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64  ion of type void
182a0 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
182b0 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  3*,const char*, 
182c0 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  int)..** The sec
182d0 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66  ond should be of
182e0 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54   type (void*). T
182f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
18300 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69  nvoked by the li
18310 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65  brary.** in thre
18320 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63 75  e separate circu
18330 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69  mstances, identi
18340 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c 75  fied by the valu
18350 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 0a  e passed as the.
18360 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
18370 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72  ter. If the four
18380 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
18390 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  0, then the data
183a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
183b0 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ** passed as the
183c0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
183d0 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f   has just been o
183e0 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64  pened. The third
183f0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69   argument.** poi
18400 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72 20  nts to a buffer 
18410 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e  containing the n
18420 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20  ame of the main 
18430 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49  database file. I
18440 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20  f the.** fourth 
18450 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20  parameter is 1, 
18460 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61  then the SQL sta
18470 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20  tement that the 
18480 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a  third parameter.
18490 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73  ** points to has
184a0 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63 75   just been execu
184b0 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  ted. Or, if the 
184c0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
184d0 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74   is 2, then.** t
184e0 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65  he connection be
184f0 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74 68  ing passed as th
18500 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18510 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73  er is being clos
18520 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64  ed. The.** third
18530 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 61   parameter is pa
18540 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69  ssed NULL In thi
18550 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d  s case.  An exam
18560 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ple of using thi
18570 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  s.** configurati
18580 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  on option can be
18590 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65   seen in the "te
185a0 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75  st_sqllog.c" sou
185b0 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74  rce file in.** t
185c0 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c  he canonical SQL
185d0 69 74 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e  ite source tree.
185e0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
185f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50  LITE_CONFIG_MMAP
18600 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  _SIZE]].** <dt>S
18610 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
18620 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53  P_SIZE.** <dd>^S
18630 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41  QLITE_CONFIG_MMA
18640 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f  P_SIZE takes two
18650 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
18660 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20  (sqlite3_int64) 
18670 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61  values.** that a
18680 72 65 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  re the default m
18690 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28  map size limit (
186a0 74 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  the default sett
186b0 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47  ing for.** [PRAG
186c0 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61  MA mmap_size]) a
186d0 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61  nd the maximum a
186e0 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65  llowed mmap size
186f0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20   limit..** ^The 
18700 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20  default setting 
18710 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
18720 6e 20 62 79 20 65 61 63 68 20 64 61 74 61 62 61  n by each databa
18730 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73  se connection us
18740 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68  ing.** either th
18750 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  e [PRAGMA mmap_s
18760 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72  ize] command, or
18770 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   by using the.**
18780 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d   [SQLITE_FCNTL_M
18790 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63  MAP_SIZE] file c
187a0 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d  ontrol.  ^(The m
187b0 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d  aximum allowed m
187c0 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 77 69 6c 6c  map size.** will
187d0 20 62 65 20 73 69 6c 65 6e 74 6c 79 20 74 72 75   be silently tru
187e0 6e 63 61 74 65 64 20 69 66 20 6e 65 63 65 73 73  ncated if necess
187f0 61 72 79 20 73 6f 20 74 68 61 74 20 69 74 20 64  ary so that it d
18800 6f 65 73 20 6e 6f 74 20 65 78 63 65 65 64 20 74  oes not exceed t
18810 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  he.** compile-ti
18820 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d 61 70 20  me maximum mmap 
18830 73 69 7a 65 20 73 65 74 20 62 79 20 74 68 65 0a  size set by the.
18840 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4d  ** [SQLITE_MAX_M
18850 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d 70 69 6c  MAP_SIZE] compil
18860 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e  e-time option.)^
18870 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65 72 20 61  .** ^If either a
18880 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
18890 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67 61 74 69  option is negati
188a0 76 65 2c 20 74 68 65 6e 20 74 68 61 74 20 61 72  ve, then that ar
188b0 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 63 68 61  gument is.** cha
188c0 6e 67 65 64 20 74 6f 20 69 74 73 20 63 6f 6d 70  nged to its comp
188d0 69 6c 65 2d 74 69 6d 65 20 64 65 66 61 75 6c 74  ile-time default
188e0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
188f0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
18900 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  APSIZE]].** <dt>
18910 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
18920 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a 2a 2a 20  N32_HEAPSIZE.** 
18930 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
18940 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
18950 50 53 49 5a 45 20 6f 70 74 69 6f 6e 20 69 73 20  PSIZE option is 
18960 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
18970 66 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  f SQLite is.** c
18980 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64  ompiled for Wind
18990 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51  ows with the [SQ
189a0 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
189b0 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
189c0 20 6d 61 63 72 6f 0a 2a 2a 20 64 65 66 69 6e 65   macro.** define
189d0 64 2e 20 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  d. ^SQLITE_CONFI
189e0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
189f0 20 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20   takes a 32-bit 
18a00 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
18a10 20 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73   value.** that s
18a20 70 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78  pecifies the max
18a30 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65  imum size of the
18a40 20 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a   created heap..*
18a50 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
18a60 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53  NFIG_PCACHE_HDRS
18a70 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
18a80 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
18a90 48 44 52 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  HDRSZ.** <dd>^Th
18aa0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18ab0 50 43 41 43 48 45 5f 48 44 52 53 5a 20 6f 70 74  PCACHE_HDRSZ opt
18ac0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
18ad0 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
18ae0 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74  ch.** is a point
18af0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
18b00 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 74 6f   and writes into
18b10 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 74 68   that integer th
18b20 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72  e number of extr
18b30 61 0a 2a 2a 20 62 79 74 65 73 20 70 65 72 20 70  a.** bytes per p
18b40 61 67 65 20 72 65 71 75 69 72 65 64 20 66 6f 72  age required for
18b50 20 65 61 63 68 20 70 61 67 65 20 69 6e 20 5b 53   each page in [S
18b60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
18b70 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 20  ECACHE]..** The 
18b80 61 6d 6f 75 6e 74 20 6f 66 20 65 78 74 72 61 20  amount of extra 
18b90 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20 63  space required c
18ba0 61 6e 20 63 68 61 6e 67 65 20 64 65 70 65 6e 64  an change depend
18bb0 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  ing on the compi
18bc0 6c 65 72 2c 0a 2a 2a 20 74 61 72 67 65 74 20 70  ler,.** target p
18bd0 6c 61 74 66 6f 72 6d 2c 20 61 6e 64 20 53 51 4c  latform, and SQL
18be0 69 74 65 20 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a  ite version..**.
18bf0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
18c00 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a 2a 20 3c 64  IG_PMASZ]].** <d
18c10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
18c20 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PMASZ.** <dd>^Th
18c30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18c40 50 4d 41 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  PMASZ option tak
18c50 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
18c60 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
18c70 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 69 6e  s an unsigned in
18c80 74 65 67 65 72 20 61 6e 64 20 73 65 74 73 20 74  teger and sets t
18c90 68 65 20 22 4d 69 6e 69 6d 75 6d 20 50 4d 41 20  he "Minimum PMA 
18ca0 53 69 7a 65 22 20 66 6f 72 20 74 68 65 20 6d 75  Size" for the mu
18cb0 6c 74 69 74 68 72 65 61 64 65 64 0a 2a 2a 20 73  ltithreaded.** s
18cc0 6f 72 74 65 72 20 74 6f 20 74 68 61 74 20 69 6e  orter to that in
18cd0 74 65 67 65 72 2e 20 20 54 68 65 20 64 65 66 61  teger.  The defa
18ce0 75 6c 74 20 6d 69 6e 69 6d 75 6d 20 50 4d 41 20  ult minimum PMA 
18cf0 53 69 7a 65 20 69 73 20 73 65 74 20 62 79 20 74  Size is set by t
18d00 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 4f  he.** [SQLITE_SO
18d10 52 54 45 52 5f 50 4d 41 53 5a 5d 20 63 6f 6d 70  RTER_PMASZ] comp
18d20 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
18d30 20 20 4e 65 77 20 74 68 72 65 61 64 73 20 61 72    New threads ar
18d40 65 20 6c 61 75 6e 63 68 65 64 0a 2a 2a 20 74 6f  e launched.** to
18d50 20 68 65 6c 70 20 77 69 74 68 20 73 6f 72 74 20   help with sort 
18d60 6f 70 65 72 61 74 69 6f 6e 73 20 77 68 65 6e 20  operations when 
18d70 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 73 6f  multithreaded so
18d80 72 74 69 6e 67 0a 2a 2a 20 69 73 20 65 6e 61 62  rting.** is enab
18d90 6c 65 64 20 28 75 73 69 6e 67 20 74 68 65 20 5b  led (using the [
18da0 50 52 41 47 4d 41 20 74 68 72 65 61 64 73 5d 20  PRAGMA threads] 
18db0 63 6f 6d 6d 61 6e 64 29 20 61 6e 64 20 74 68 65  command) and the
18dc0 20 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65   amount of conte
18dd0 6e 74 0a 2a 2a 20 74 6f 20 62 65 20 73 6f 72 74  nt.** to be sort
18de0 65 64 20 65 78 63 65 65 64 73 20 74 68 65 20 70  ed exceeds the p
18df0 61 67 65 20 73 69 7a 65 20 74 69 6d 65 73 20 74  age size times t
18e00 68 65 20 6d 69 6e 69 6d 75 6d 20 6f 66 20 74 68  he minimum of th
18e10 65 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 63 61 63  e.** [PRAGMA cac
18e20 68 65 5f 73 69 7a 65 5d 20 73 65 74 74 69 6e 67  he_size] setting
18e30 20 61 6e 64 20 74 68 69 73 20 76 61 6c 75 65 2e   and this value.
18e40 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
18e50 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
18e60 53 50 49 4c 4c 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  SPILL]].** <dt>S
18e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
18e80 54 4a 52 4e 4c 5f 53 50 49 4c 4c 0a 2a 2a 20 3c  TJRNL_SPILL.** <
18e90 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  dd>^The SQLITE_C
18ea0 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
18eb0 50 49 4c 4c 20 6f 70 74 69 6f 6e 20 74 61 6b 65  PILL option take
18ec0 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d  s a single param
18ed0 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 62 65  eter which.** be
18ee0 63 6f 6d 65 73 20 74 68 65 20 5b 73 74 61 74 65  comes the [state
18ef0 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 5d 20 73 70  ment journal] sp
18f00 69 6c 6c 2d 74 6f 2d 64 69 73 6b 20 74 68 72 65  ill-to-disk thre
18f10 73 68 6f 6c 64 2e 20 20 0a 2a 2a 20 5b 53 74 61  shold.  .** [Sta
18f20 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 5d  tement journals]
18f30 20 61 72 65 20 68 65 6c 64 20 69 6e 20 6d 65 6d   are held in mem
18f40 6f 72 79 20 75 6e 74 69 6c 20 74 68 65 69 72 20  ory until their 
18f50 73 69 7a 65 20 28 69 6e 20 62 79 74 65 73 29 0a  size (in bytes).
18f60 2a 2a 20 65 78 63 65 65 64 73 20 74 68 69 73 20  ** exceeds this 
18f70 74 68 72 65 73 68 6f 6c 64 2c 20 61 74 20 77 68  threshold, at wh
18f80 69 63 68 20 70 6f 69 6e 74 20 74 68 65 79 20 61  ich point they a
18f90 72 65 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  re written to di
18fa0 73 6b 2e 0a 2a 2a 20 4f 72 20 69 66 20 74 68 65  sk..** Or if the
18fb0 20 74 68 72 65 73 68 6f 6c 64 20 69 73 20 2d 31   threshold is -1
18fc0 2c 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72  , statement jour
18fd0 6e 61 6c 73 20 61 72 65 20 61 6c 77 61 79 73 20  nals are always 
18fe0 68 65 6c 64 0a 2a 2a 20 65 78 63 6c 75 73 69 76  held.** exclusiv
18ff0 65 6c 79 20 69 6e 20 6d 65 6d 6f 72 79 2e 0a 2a  ely in memory..*
19000 2a 20 53 69 6e 63 65 20 6d 61 6e 79 20 73 74 61  * Since many sta
19010 74 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20  tement journals 
19020 6e 65 76 65 72 20 62 65 63 6f 6d 65 20 6c 61 72  never become lar
19030 67 65 2c 20 73 65 74 74 69 6e 67 20 74 68 65 20  ge, setting the 
19040 73 70 69 6c 6c 0a 2a 2a 20 74 68 72 65 73 68 6f  spill.** thresho
19050 6c 64 20 74 6f 20 61 20 76 61 6c 75 65 20 73 75  ld to a value su
19060 63 68 20 61 73 20 36 34 4b 69 42 20 63 61 6e 20  ch as 64KiB can 
19070 67 72 65 61 74 6c 79 20 72 65 64 75 63 65 20 74  greatly reduce t
19080 68 65 20 61 6d 6f 75 6e 74 20 6f 66 0a 2a 2a 20  he amount of.** 
19090 49 2f 4f 20 72 65 71 75 69 72 65 64 20 74 6f 20  I/O required to 
190a0 73 75 70 70 6f 72 74 20 73 74 61 74 65 6d 65 6e  support statemen
190b0 74 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  t rollback..** T
190c0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
190d0 20 66 6f 72 20 74 68 69 73 20 73 65 74 74 69 6e   for this settin
190e0 67 20 69 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  g is controlled 
190f0 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
19100 45 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c  E_STMTJRNL_SPILL
19110 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
19120 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  ption..** </dl>.
19130 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19140 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
19150 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
19160 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19170 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
19180 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
19190 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
191a0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
191b0 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
191c0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
191d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
191e0 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
191f0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
19200 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
19210 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
19220 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
19230 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
19240 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
19250 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19260 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
19270 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
19280 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
19290 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
192a0 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
192b0 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
192c0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
192d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
192e0 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
192f0 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
19300 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
19310 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
19320 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
19330 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
19340 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
19350 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19360 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
19370 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
19380 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
19390 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
193a0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
193b0 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
193c0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
193d0 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
193e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
193f0 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
19400 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
19410 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
19420 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
19430 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
19440 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
19450 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19460 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
19470 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
19480 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19490 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
194a0 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
194b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
194c0 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
194d0 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
194e0 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
194f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19500 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
19510 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
19520 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
19530 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
19540 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
19550 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
19560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19570 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
19580 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
19590 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
195a0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
195b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
195c0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
195d0 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   20  /* int */.#
195e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
195f0 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20  NFIG_SQLLOG     
19600 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67    21  /* xSqllog
19610 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
19620 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
19630 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32  _MMAP_SIZE    22
19640 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74    /* sqlite3_int
19650 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  64, sqlite3_int6
19660 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
19670 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
19680 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32  _HEAPSIZE      2
19690 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  3  /* int nByte 
196a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
196b0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
196c0 48 44 52 53 5a 20 20 20 20 20 20 20 20 32 34 20  HDRSZ        24 
196d0 20 2f 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a   /* int *psz */.
196e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
196f0 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20  ONFIG_PMASZ     
19700 20 20 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a            25  /*
19710 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a   unsigned int sz
19720 50 6d 61 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  Pma */.#define S
19730 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
19740 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 20 20 20 20  TJRNL_SPILL     
19750 20 32 36 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74   26  /* int nByt
19760 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e */../*.** CAPI
19770 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
19780 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
19790 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
197a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
197b0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
197c0 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
197d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
197e0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
197f0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
19800 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
19810 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
19820 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
19830 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
19840 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
19850 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
19860 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
19870 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
19880 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
19890 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
198a0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
198b0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
198c0 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
198d0 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
198e0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
198f0 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
19900 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
19910 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
19920 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
19930 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
19940 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
19950 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
19960 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
19970 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
19980 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
19990 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
199a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
199b0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
199c0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
199d0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
199e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
199f0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
19a00 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
19a10 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
19a20 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
19a30 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
19a40 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
19a50 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
19a60 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
19a70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
19a80 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
19a90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
19aa0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
19ab0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
19ac0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
19ad0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
19ae0 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
19af0 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
19b00 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
19b10 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
19b20 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
19b30 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
19b40 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
19b50 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
19b60 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
19b70 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
19b80 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
19b90 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
19ba0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
19bb0 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
19bc0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
19bd0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
19be0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
19bf0 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
19c00 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
19c10 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
19c20 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
19c30 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
19c40 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
19c50 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
19c60 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
19c70 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
19c80 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
19c90 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
19ca0 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
19cb0 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
19cc0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
19cd0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
19ce0 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
19cf0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
19d00 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
19d10 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
19d20 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
19d30 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
19d40 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
19d50 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
19d60 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
19d70 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
19d80 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
19d90 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
19da0 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
19db0 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
19dc0 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
19dd0 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
19de0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
19df0 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
19e00 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
19e10 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
19e20 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
19e30 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
19e40 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
19e50 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
19e60 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
19e70 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
19e80 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
19e90 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
19ea0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
19eb0 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
19ec0 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
19ed0 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
19ee0 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
19ef0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
19f00 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
19f10 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
19f20 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
19f30 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
19f40 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19f50 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
19f60 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
19f70 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
19f80 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
19f90 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
19fa0 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
19fb0 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
19fc0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
19fd0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
19fe0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
19ff0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1a000 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
1a010 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
1a020 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
1a030 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
1a040 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
1a050 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
1a060 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
1a070 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
1a080 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
1a090 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a0a0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
1a0b0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
1a0c0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
1a0d0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
1a0e0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
1a0f0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
1a100 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
1a110 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
1a120 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
1a130 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
1a140 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
1a150 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
1a160 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
1a170 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
1a180 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
1a190 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
1a1a0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
1a1b0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
1a1c0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
1a1d0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
1a1e0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
1a1f0 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
1a200 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
1a210 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
1a220 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
1a230 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
1a240 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
1a250 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
1a260 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
1a270 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
1a280 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
1a290 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
1a2a0 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
1a2b0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
1a2c0 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
1a2d0 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
1a2e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
1a2f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
1a300 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
1a310 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
1a320 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
1a330 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
1a340 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
1a350 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
1a360 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
1a370 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
1a380 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
1a390 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1a3a0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
1a3b0 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
1a3c0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
1a3d0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
1a3e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1a3f0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1a400 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
1a410 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
1a420 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
1a430 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
1a440 64 69 73 61 62 6c 65 20 74 68 65 20 74 77 6f 2d  disable the two-
1a450 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 65 72 73  argument.** vers
1a460 69 6f 6e 20 6f 66 20 74 68 65 20 5b 66 74 73 33  ion of the [fts3
1a470 5f 74 6f 6b 65 6e 69 7a 65 72 28 29 5d 20 66 75  _tokenizer()] fu
1a480 6e 63 74 69 6f 6e 20 77 68 69 63 68 20 69 73 20  nction which is 
1a490 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  part of the.** [
1a4a0 46 54 53 33 5d 20 66 75 6c 6c 2d 74 65 78 74 20  FTS3] full-text 
1a4b0 73 65 61 72 63 68 20 65 6e 67 69 6e 65 20 65 78  search engine ex
1a4c0 74 65 6e 73 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72  tension..** Ther
1a4d0 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
1a4e0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
1a4f0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
1a500 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
1a510 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
1a520 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
1a530 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28 29  fts3_tokenizer()
1a540 20 6f 72 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20   or.** positive 
1a550 74 6f 20 65 6e 61 62 6c 65 20 66 74 73 33 5f 74  to enable fts3_t
1a560 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 20 6e 65  okenizer() or ne
1a570 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
1a580 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 75  the setting.** u
1a590 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
1a5a0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a5b0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
1a5c0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
1a5d0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
1a5e0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
1a5f0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
1a600 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 20   fts3_tokenizer 
1a610 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  is disabled or e
1a620 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
1a630 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
1a640 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1a650 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
1a660 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
1a670 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
1a680 20 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20   new setting is 
1a690 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
1a6a0 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
1a6b0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
1a6c0 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45  IG_ENABLE_LOAD_E
1a6d0 58 54 45 4e 53 49 4f 4e 3c 2f 64 74 3e 0a 2a 2a  XTENSION</dt>.**
1a6e0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
1a6f0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
1a700 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
1a710 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
1a720 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 0a 2a  d_extension()].*
1a730 2a 20 69 6e 74 65 72 66 61 63 65 20 69 6e 64 65  * interface inde
1a740 70 65 6e 64 65 6e 74 6c 79 20 6f 66 20 74 68 65  pendently of the
1a750 20 5b 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e   [load_extension
1a760 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ()] SQL function
1a770 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
1a780 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78  3_enable_load_ex
1a790 74 65 6e 73 69 6f 6e 28 29 5d 20 41 50 49 20 65  tension()] API e
1a7a0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
1a7b0 65 73 20 62 6f 74 68 20 74 68 65 0a 2a 2a 20 43  es both the.** C
1a7c0 2d 41 50 49 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  -API [sqlite3_lo
1a7d0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
1a7e0 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63  and the SQL func
1a7f0 74 69 6f 6e 20 5b 6c 6f 61 64 5f 65 78 74 65 6e  tion [load_exten
1a800 73 69 6f 6e 28 29 5d 2e 0a 2a 2a 20 54 68 65 72  sion()]..** Ther
1a810 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
1a820 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
1a830 65 6e 74 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68  ents..** When th
1a840 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1a850 20 74 6f 20 74 68 69 73 20 69 6e 74 65 72 66 61   to this interfa
1a860 63 65 20 69 73 20 31 2c 20 74 68 65 6e 20 6f 6e  ce is 1, then on
1a870 6c 79 20 74 68 65 20 43 2d 41 50 49 20 69 73 0a  ly the C-API is.
1a880 2a 2a 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 74  ** enabled and t
1a890 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
1a8a0 72 65 6d 61 69 6e 73 20 64 69 73 61 62 6c 65 64  remains disabled
1a8b0 2e 20 20 49 66 20 74 68 65 20 66 69 72 73 74 20  .  If the first 
1a8c0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
1a8d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
1a8e0 20 30 2c 20 74 68 65 6e 20 62 6f 74 68 20 74 68   0, then both th
1a8f0 65 20 43 2d 41 50 49 20 61 6e 64 20 74 68 65 20  e C-API and the 
1a900 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  SQL function are
1a910 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 20 49 66   disabled..** If
1a920 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
1a930 65 6e 74 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ent is -1, then 
1a940 6e 6f 20 63 68 61 6e 67 65 73 20 61 72 65 20 6d  no changes are m
1a950 61 64 65 20 74 6f 20 73 74 61 74 65 20 6f 66 20  ade to state of 
1a960 65 69 74 68 65 72 20 74 68 65 0a 2a 2a 20 43 2d  either the.** C-
1a970 41 50 49 20 6f 72 20 74 68 65 20 53 51 4c 20 66  API or the SQL f
1a980 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
1a990 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1a9a0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
1a9b0 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
1a9c0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
1a9d0 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
1a9e0 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
1a9f0 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78  [sqlite3_load_ex
1aa00 74 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72  tension()] inter
1aa10 66 61 63 65 0a 2a 2a 20 69 73 20 64 69 73 61 62  face.** is disab
1aa20 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 20 66  led or enabled f
1aa30 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
1aa40 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
1aa50 70 61 72 61 6d 65 74 65 72 20 6d 61 79 0a 2a 2a  parameter may.**
1aa60 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
1aa70 65 72 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  er, in which cas
1aa80 65 20 74 68 65 20 6e 65 77 20 73 65 74 74 69 6e  e the new settin
1aa90 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
1aaa0 64 20 62 61 63 6b 2e 0a 2a 2a 20 3c 2f 64 64 3e  d back..** </dd>
1aab0 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
1aac0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1aad0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
1aae0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31 30  E             10
1aaf0 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  01 /* void* int 
1ab00 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
1ab10 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
1ab20 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 20  NABLE_FKEY      
1ab30 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e 74       1002 /* int
1ab40 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
1ab50 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
1ab60 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
1ab70 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20 69         1003 /* i
1ab80 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
1ab90 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
1aba0 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54  IG_ENABLE_FTS3_T
1abb0 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f 2a  OKENIZER 1004 /*
1abc0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
1abd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
1abe0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41 44  NFIG_ENABLE_LOAD
1abf0 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35 20  _EXTENSION 1005 
1ac00 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a  /* int int* */..
1ac10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1ac20 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62   Enable Or Disab
1ac30 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73 75  le Extended Resu
1ac40 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48  lt Codes.** METH
1ac50 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1ac60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1ac70 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
1ac80 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65  odes() routine e
1ac90 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
1aca0 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e  es the.** [exten
1acb0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
1acc0 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c  ] feature of SQL
1acd0 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64  ite. ^The extend
1ace0 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64  ed result.** cod
1acf0 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  es are disabled 
1ad00 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68  by default for h
1ad10 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74  istorical compat
1ad20 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49  ibility..*/.SQLI
1ad30 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1ad40 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
1ad50 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
1ad60 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
1ad70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ad80 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
1ad90 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
1ada0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  ite3.**.** ^Each
1adb0 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20 53   entry in most S
1adc0 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65 78  QLite tables (ex
1add0 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f 55  cept for [WITHOU
1ade0 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 29  T ROWID] tables)
1adf0 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75 65  .** has a unique
1ae00 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a   64-bit signed.*
1ae10 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61  * integer key ca
1ae20 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20  lled the [ROWID 
1ae30 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65  | "rowid"]. ^The
1ae40 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73   rowid is always
1ae50 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73   available.** as
1ae60 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63   an undeclared c
1ae70 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49  olumn named ROWI
1ae80 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49  D, OID, or _ROWI
1ae90 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  D_ as long as th
1aea0 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65  ose.** names are
1aeb0 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62   not also used b
1aec0 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  y explicitly dec
1aed0 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e  lared columns. ^
1aee0 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20  If.** the table 
1aef0 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20  has a column of 
1af00 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52  type [INTEGER PR
1af10 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20  IMARY KEY] then 
1af20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  that column.** i
1af30 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20  s another alias 
1af40 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a  for the rowid..*
1af50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1af60 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1af70 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63 65  wid(D) interface
1af80 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
1af90 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20  wid] of the .** 
1afa0 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63 63  most recent succ
1afb0 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
1afc0 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61 62  into a rowid tab
1afd0 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20 74  le or [virtual t
1afe0 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61  able].** on data
1aff0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b000 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69  D..** ^Inserts i
1b010 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57  nto [WITHOUT ROW
1b020 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e  ID] tables are n
1b030 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20  ot recorded..** 
1b040 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
1b050 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f  l [INSERT]s into
1b060 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a   rowid tables.**
1b070 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
1b080 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61 62  red on the datab
1b090 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
1b0a0 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  , .** then sqlit
1b0b0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1b0c0 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73 20  owid(D) returns 
1b0d0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  zero..**.** ^(If
1b0e0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63   an [INSERT] occ
1b0f0 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69  urs within a tri
1b100 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61  gger or within a
1b110 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
1b120 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e  .** method, then
1b130 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1b140 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72  ll return the [r
1b150 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73  owid] of the ins
1b160 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20  erted.** row as 
1b170 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67  long as the trig
1b180 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74  ger or virtual t
1b190 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72  able method is r
1b1a0 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f  unning..** But o
1b1b0 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20  nce the trigger 
1b1c0 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
1b1d0 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68   method ends, th
1b1e0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1b1f0 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75   .** by this rou
1b200 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20  tine reverts to 
1b210 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f  what it was befo
1b220 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  re the trigger o
1b230 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62  r virtual.** tab
1b240 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e  le method began.
1b250 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e  )^.**.** ^An [IN
1b260 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73  SERT] that fails
1b270 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72   due to a constr
1b280 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69  aint violation i
1b290 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65  s not a.** succe
1b2a0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61  ssful [INSERT] a
1b2b0 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nd does not chan
1b2c0 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ge the value ret
1b2d0 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a  urned by this.**
1b2e0 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73   routine.  ^Thus
1b2f0 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c   INSERT OR FAIL,
1b300 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52   INSERT OR IGNOR
1b310 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c  E, INSERT OR ROL
1b320 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e  LBACK,.** and IN
1b330 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61  SERT OR ABORT ma
1b340 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f  ke no changes to
1b350 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1b360 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75  e of this.** rou
1b370 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20  tine when their 
1b380 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e  insertion fails.
1b390 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20    ^(When INSERT 
1b3a0 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e  OR REPLACE.** en
1b3b0 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74  counters a const
1b3c0 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c  raint violation,
1b3d0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69   it does not fai
1b3e0 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52  l.  The.** INSER
1b3f0 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63  T continues to c
1b400 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20  ompletion after 
1b410 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68  deleting rows th
1b420 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65  at caused.** the
1b430 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62   constraint prob
1b440 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52  lem so INSERT OR
1b450 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c   REPLACE will al
1b460 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74  ways change.** t
1b470 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
1b480 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
1b490 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  e.)^.**.** ^For 
1b4a0 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
1b4b0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e  this routine, an
1b4c0 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e   [INSERT] is con
1b4d0 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65  sidered to.** be
1b4e0 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e   successful even
1b4f0 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71   if it is subseq
1b500 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61  uently rolled ba
1b510 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66  ck..**.** This f
1b520 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73  unction is acces
1b530 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61  sible to SQL sta
1b540 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a  tements via the.
1b550 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f  ** [last_insert_
1b560 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63  rowid() SQL func
1b570 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
1b580 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1b590 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77  d performs a new
1b5a0 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65   [INSERT] on the
1b5b0 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73   same.** databas
1b5c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  e connection whi
1b5d0 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  le the [sqlite3_
1b5e0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1b5f0 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  d()].** function
1b600 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20   is running and 
1b610 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65  thus changes the
1b620 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
1b630 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  wid],.** then th
1b640 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1b650 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73   by [sqlite3_las
1b660 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
1b670 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63  ] is.** unpredic
1b680 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20  table and might 
1b690 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72  not equal either
1b6a0 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20   the old or the 
1b6b0 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65  new.** last inse
1b6c0 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53  rt [rowid]..*/.S
1b6d0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
1b6e0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1b6f0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
1b700 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
1b710 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1b720 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
1b730 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
1b740 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1b750 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  e3.**.** ^This f
1b760 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1b770 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1b780 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e 73  ws modified, ins
1b790 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65  erted or.** dele
1b7a0 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
1b7b0 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
1b7c0 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
1b7d0 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  E or DELETE.** s
1b7e0 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65 20  tatement on the 
1b7f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b800 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62 79  ion specified by
1b810 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
1b820 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74 69  ter..** ^Executi
1b830 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
1b840 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
1b850 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64 69  nt does not modi
1b860 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  fy the value.** 
1b870 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
1b880 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
1b890 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d   ^Only changes m
1b8a0 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79 20  ade directly by 
1b8b0 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44 41  the INSERT, UPDA
1b8c0 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61  TE or DELETE sta
1b8d0 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63 6f  tement are.** co
1b8e0 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69 6c  nsidered - auxil
1b8f0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
1b900 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20 54  sed by [CREATE T
1b910 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
1b920 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  s], .** [foreign
1b930 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f 72   key actions] or
1b940 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74   [REPLACE] const
1b950 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
1b960 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1b970 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65 73  ..** .** Changes
1b980 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
1b990 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64 20  are intercepted 
1b9a0 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44 20  by .** [INSTEAD 
1b9b0 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e 53  OF trigger | INS
1b9c0 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73  TEAD OF triggers
1b9d0 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
1b9e0 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a 2a  d. ^The value .*
1b9f0 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
1ba00 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1ba10 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65  immediately afte
1ba20 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  r an INSERT, UPD
1ba30 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45 54  ATE or .** DELET
1ba40 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e 20  E statement run 
1ba50 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c 77  on a view is alw
1ba60 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20 63  ays zero. Only c
1ba70 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20 72  hanges made to r
1ba80 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20 61  eal .** tables a
1ba90 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
1baa0 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f 72  * Things are mor
1bab0 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69 66  e complicated if
1bac0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
1bad0 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
1bae0 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 77  is.** executed w
1baf0 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20 70  hile a trigger p
1bb00 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69 6e  rogram is runnin
1bb10 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70 70  g. This may happ
1bb20 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72 6f  en if the.** pro
1bb30 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b 63  gram uses the [c
1bb40 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
1bb50 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73 6f  ction], or if so
1bb60 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61 63  me other callbac
1bb70 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 6e  k.** function in
1bb80 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63 68  vokes sqlite3_ch
1bb90 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c 79  anges() directly
1bba0 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a 2a  . Essentially:.*
1bbb0 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  * .** <ul>.**   
1bbc0 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65 6e  <li> ^(Before en
1bbd0 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65 72  tering a trigger
1bbe0 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61 6c   program the val
1bbf0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ue returned by.*
1bc00 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33  *        sqlite3
1bc10 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
1bc20 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41 66  ion is saved. Af
1bc30 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72 20  ter the trigger 
1bc40 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20 20  program .**     
1bc50 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64 2c     has finished,
1bc60 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76 61   the original va
1bc70 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64 2e  lue is restored.
1bc80 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69 3e  )^.** .**   <li>
1bc90 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69 67   ^(Within a trig
1bca0 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63 68  ger program each
1bcb0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1bcc0 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20 20  and DELETE .**  
1bcd0 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74 20        statement 
1bce0 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20 72  sets the value r
1bcf0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1bd00 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
1bd10 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f 6d          upon com
1bd20 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d 61  pletion as norma
1bd30 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74 68  l. Of course, th
1bd40 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e 6f  is value will no
1bd50 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20 20  t include .**   
1bd60 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65 73       any changes
1bd70 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73 75   performed by su
1bd80 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20 74  b-triggers, as t
1bd90 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
1bda0 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
1bdb0 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73 61  value will be sa
1bdc0 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65 64  ved and restored
1bdd0 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62 2d   after each sub-
1bde0 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e 2e  trigger has run.
1bdf0 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a  )^.** </ul>.** .
1be00 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20 74  ** ^This means t
1be10 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e 67  hat if the chang
1be20 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
1be30 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20 69  n (or similar) i
1be40 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65  s used.** by the
1be50 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20 55   first INSERT, U
1be60 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
1be70 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1be80 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20 0a   a trigger, it .
1be90 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  ** returns the v
1bea0 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65 6e  alue as set when
1beb0 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74 61   the calling sta
1bec0 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78 65  tement began exe
1bed0 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 69  cuting..** ^If i
1bee0 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  t is used by the
1bef0 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73 65   second or subse
1bf00 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74 65  quent such state
1bf10 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72  ment within a tr
1bf20 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72 61  igger .** progra
1bf30 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  m, the value ret
1bf40 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20 74  urned reflects t
1bf50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1bf60 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74 68  s modified by th
1bf70 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 49  e .** previous I
1bf80 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1bf90 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1bfa0 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
1bfb0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a 2a  e trigger..**.**
1bfc0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
1bfd0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1bfe0 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
1bff0 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
1c000 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
1c010 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
1c020 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
1c030 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
1c040 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
1c050 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
1c060 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
1c070 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1c080 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
1c090 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
1c0a0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
1c0b0 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
1c0c0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
1c0d0 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
1c0e0 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
1c0f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
1c100 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
1c110 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1c120 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
1c130 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
1c140 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1c150 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1c160 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1c170 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
1c180 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74  r of rows insert
1c190 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a  ed, modified or.
1c1a0 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c  ** deleted by al
1c1b0 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44  l [INSERT], [UPD
1c1c0 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
1c1d0 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70   statements comp
1c1e0 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74  leted.** since t
1c1f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1c200 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65  ection was opene
1c210 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f  d, including tho
1c220 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a  se executed as.*
1c230 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65  * part of trigge
1c240 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65  r programs. ^Exe
1c250 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
1c260 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
1c270 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e  tement.** does n
1c280 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61  ot affect the va
1c290 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1c2a0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1c2b0 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20  anges()..** .** 
1c2c0 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73  ^Changes made as
1c2d0 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67   part of [foreig
1c2e0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61  n key actions] a
1c2f0 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  re included in t
1c300 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74  he.** count, but
1c310 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70   those made as p
1c320 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63  art of REPLACE c
1c330 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
1c340 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e  tion are.** not.
1c350 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
1c360 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
1c370 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54  ercepted by INST
1c380 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20  EAD OF triggers 
1c390 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
1c3a0 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20  ted..** .** See 
1c3b0 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
1c3c0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
1c3d0 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
1c3e0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
1c3f0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
1c400 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
1c410 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
1c420 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
1c430 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
1c440 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
1c450 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1c460 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
1c470 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
1c480 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
1c490 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
1c4a0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
1c4b0 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
1c4c0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
1c4d0 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  gful..*/.SQLITE_
1c4e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1c4f0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71  total_changes(sq
1c500 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1c510 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72  CAPI3REF: Interr
1c520 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69  upt A Long-Runni
1c530 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48  ng Query.** METH
1c540 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1c550 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1c560 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64   causes any pend
1c570 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65  ing database ope
1c580 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20  ration to abort 
1c590 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74  and.** return at
1c5a0 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70   its earliest op
1c5b0 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20  portunity. This 
1c5c0 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63  routine is typic
1c5d0 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69  ally.** called i
1c5e0 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20  n response to a 
1c5f0 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68  user action such
1c600 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61   as pressing "Ca
1c610 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c  ncel".** or Ctrl
1c620 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65  -C where the use
1c630 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71  r wants a long q
1c640 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74  uery operation t
1c650 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69  o halt.** immedi
1c660 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  ately..**.** ^It
1c670 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c   is safe to call
1c680 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72   this routine fr
1c690 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66  om a thread diff
1c6a0 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a  erent from the.*
1c6b0 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73  * thread that is
1c6c0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
1c6d0 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
1c6e0 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20  operation.  But 
1c6f0 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66  it.** is not saf
1c700 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1c710 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64  outine with a [d
1c720 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c730 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63  on] that.** is c
1c740 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63  losed or might c
1c750 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69  lose before sqli
1c760 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1c770 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
1c780 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74  If an SQL operat
1c790 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72  ion is very near
1c7a0 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74  ly finished at t
1c7b0 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20  he time when.** 
1c7c0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1c7d0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74  t() is called, t
1c7e0 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74  hen it might not
1c7f0 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75   have an opportu
1c800 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  nity.** to be in
1c810 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69  terrupted and mi
1c820 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20  ght continue to 
1c830 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a  completion..**.*
1c840 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74  * ^An SQL operat
1c850 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65  ion that is inte
1c860 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74  rrupted will ret
1c870 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  urn [SQLITE_INTE
1c880 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74  RRUPT]..** ^If t
1c890 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53  he interrupted S
1c8a0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1c8b0 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  an INSERT, UPDAT
1c8c0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
1c8d0 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61  that is inside a
1c8e0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
1c8f0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  action, then the
1c900 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74   entire transact
1c910 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72  ion.** will be r
1c920 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
1c930 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  atically..**.** 
1c940 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
1c950 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69  errupt(D) call i
1c960 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69  s in effect unti
1c970 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20  l all currently 
1c980 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1c990 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61  tatements on [da
1c9a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c9b0 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20  n] D complete.  
1c9c0 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61  ^Any new SQL sta
1c9d0 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1c9e0 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1c9f0 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1ca00 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61  terrupt() call a
1ca10 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a  nd before the .*
1ca20 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  * running statem
1ca30 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72  ents reaches zer
1ca40 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65  o are interrupte
1ca50 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64  d as if they had
1ca60 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67   been.** running
1ca70 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71   prior to the sq
1ca80 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1ca90 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51  ) call.  ^New SQ
1caa0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
1cab0 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
1cac0 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69   after the runni
1cad0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75  ng statement cou
1cae0 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  nt reaches zero 
1caf0 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63  are.** not effec
1cb00 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
1cb10 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a  e3_interrupt()..
1cb20 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71  ** ^A call to sq
1cb30 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1cb40 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77  D) that occurs w
1cb50 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f  hen there are no
1cb60 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1cb70 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20  statements is a 
1cb80 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f  no-op and has no
1cb90 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73   effect on SQL s
1cba0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
1cbb0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
1cbc0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
1cbd0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1cbe0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1cbf0 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
1cc00 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
1cc10 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  s while [sqlite3
1cc20 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a  _interrupt()].**
1cc30 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1cc40 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c   bad things will
1cc50 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a   likely happen..
1cc60 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1cc70 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
1cc80 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
1cc90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1cca0 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
1ccb0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
1ccc0 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
1ccd0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1cce0 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
1ccf0 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
1cd00 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
1cd10 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
1cd20 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
1cd30 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
1cd40 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1cd50 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
1cd60 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
1cd70 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
1cd80 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
1cd90 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
1cda0 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
1cdb0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
1cdc0 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
1cdd0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
1cde0 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
1cdf0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
1ce00 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
1ce10 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
1ce20 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
1ce30 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
1ce40 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
1ce50 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
1ce60 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
1ce70 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
1ce80 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
1ce90 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
1cea0 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
1ceb0 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
1cec0 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
1ced0 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
1cee0 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
1cef0 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
1cf00 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
1cf10 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
1cf20 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
1cf30 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
1cf40 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
1cf50 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
1cf60 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
1cf70 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
1cf80 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
1cf90 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
1cfa0 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
1cfb0 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
1cfc0 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
1cfd0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1cfe0 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
1cff0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
1d000 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
1d010 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
1d020 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
1d030 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
1d040 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1d050 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1d060 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
1d070 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1d080 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
1d090 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
1d0a0 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
1d0b0 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
1d0c0 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
1d0d0 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
1d0e0 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
1d0f0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
1d100 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
1d110 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
1d120 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
1d130 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
1d140 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
1d150 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1d160 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
1d170 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
1d180 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
1d190 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
1d1a0 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
1d1b0 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
1d1c0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
1d1d0 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
1d1e0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
1d1f0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1d200 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
1d210 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
1d220 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
1d230 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1d240 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
1d250 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1d260 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
1d270 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
1d280 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
1d290 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
1d2a0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
1d2b0 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
1d2c0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
1d2d0 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49  e order..*/.SQLI
1d2e0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1d2f0 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73  e3_complete(cons
1d300 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51  t char *sql);.SQ
1d310 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1d320 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1d330 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
1d340 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d350 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
1d360 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
1d370 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
1d380 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ors.** KEYWORDS:
1d390 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63   {busy-handler c
1d3a0 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68  allback} {busy h
1d3b0 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  andler}.** METHO
1d3c0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1d3d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75   ^The sqlite3_bu
1d3e0 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50  sy_handler(D,X,P
1d3f0 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  ) routine sets a
1d400 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1d410 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67  on X.** that mig
1d420 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1d430 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
1d440 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
1d450 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
1d460 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
1d470 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74  e table associat
1d480 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61  ed with.** [data
1d490 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1d4a0 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20   D when another 
1d4b0 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
1d4c0 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62  cess has the tab
1d4d0 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68  le locked..** Th
1d4e0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
1d4f0 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61  andler() interfa
1d500 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d  ce is used to im
1d510 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69  plement.** [sqli
1d520 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1d530 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  ()] and [PRAGMA 
1d540 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a  busy_timeout]..*
1d550 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
1d560 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1d570 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
1d580 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74  _BUSY].** is ret
1d590 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1d5a0 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
1d5b0 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
1d5c0 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1d5d0 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
1d5e0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
1d5f0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
1d600 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
1d610 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
1d620 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1d630 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
1d640 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
1d650 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1d660 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
1d670 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
1d680 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1d690 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1d6a0 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
1d6b0 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
1d6c0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1d6d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1d6e0 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
1d6f0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
1d700 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
1d710 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f  n invoked previo
1d720 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d  usly for the sam
1d730 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
1d740 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
1d750 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
1d760 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
1d770 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
1d780 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
1d790 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1d7a0 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
1d7b0 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e  _BUSY] is return
1d7c0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  ed.** to the app
1d7d0 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  lication..** ^If
1d7e0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1d7f0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1d800 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
1d810 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
1d820 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1d830 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63  tabase and the c
1d840 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
1d850 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
1d860 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
1d870 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
1d880 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
1d890 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1d8a0 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
1d8b0 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
1d8c0 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
1d8d0 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
1d8e0 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
1d8f0 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
1d900 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
1d910 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
1d920 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
1d930 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1d940 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1d950 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ion instead of i
1d960 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20  nvoking the .** 
1d970 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1d980 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
1d990 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
1d9a0 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1d9b0 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
1d9c0 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
1d9d0 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
1d9e0 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1d9f0 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
1da00 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1da10 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
1da20 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
1da30 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
1da40 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
1da50 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
1da60 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
1da70 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
1da80 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1da90 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
1daa0 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
1dab0 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
1dac0 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
1dad0 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1dae0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
1daf0 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
1db00 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
1db10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
1db20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
1db30 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
1db40 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
1db50 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
1db60 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
1db70 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1db80 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
1db90 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
1dba0 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
1dbb0 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
1dbc0 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
1dbd0 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
1dbe0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
1dbf0 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
1dc00 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
1dc10 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1dc20 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  LL..**.** ^(Ther
1dc30 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1dc40 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1dc50 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1dc60 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1dc70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1dc80 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1dc90 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1dca0 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1dcb0 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1dcc0 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1dcd0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1dce0 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1dcf0 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ** or evaluating
1dd00 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1dd10 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68  meout=N] will ch
1dd20 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79  ange the.** busy
1dd30 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75   handler and thu
1dd40 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76  s clear any prev
1dd50 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20  iously set busy 
1dd60 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
1dd70 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1dd80 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
1dd90 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
1dda0 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
1ddb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ddc0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1ddd0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1dde0 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  er.  In other wo
1ddf0 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79  rds,.** the busy
1de00 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20   handler is not 
1de10 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20  reentrant.  Any 
1de20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1de30 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1de40 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1de50 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1de60 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1de70 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1de80 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1de90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1dea0 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1deb0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1dec0 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ler..*/.SQLITE_A
1ded0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
1dee0 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  usy_handler(sqli
1def0 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69 64  te3*,int(*)(void
1df00 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a 0a  *,int),void*);..
1df10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1df20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
1df30 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ut.** METHOD: sq
1df40 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1df50 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
1df60 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1df70 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61  andler | busy ha
1df80 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65  ndler] that slee
1df90 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63  ps.** for a spec
1dfa0 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  ified amount of 
1dfb0 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c  time when a tabl
1dfc0 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54  e is locked.  ^T
1dfd0 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69  he handler.** wi
1dfe0 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c  ll sleep multipl
1dff0 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74  e times until at
1e000 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
1e010 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
1e020 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63  ping.** have acc
1e030 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65  umulated.  ^Afte
1e040 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  r at least "ms" 
1e050 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
1e060 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65  sleeping,.** the
1e070 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73   handler returns
1e080 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73 20   0 which causes 
1e090 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e0a0 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53   to return.** [S
1e0b0 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a  QLITE_BUSY]..**.
1e0c0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
1e0d0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
1e0e0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
1e0f0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
1e100 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
1e110 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
1e120 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
1e130 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1e140 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1e150 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
1e160 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1e170 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1e180 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  t any given mome
1e190 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
1e1a0 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
1e1b0 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
1e1c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1e1d0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
1e1e0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
1e1f0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
1e200 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
1e210 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
1e220 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ed.)^.**.** See 
1e230 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62  also:  [PRAGMA b
1e240 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a  usy_timeout].*/.
1e250 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1e260 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1e270 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
1e280 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
1e290 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
1e2a0 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
1e2b0 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
1e2c0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1e2d0 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te3.**.** This i
1e2e0 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
1e2f0 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
1e300 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
1e310 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1e320 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
1e330 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
1e340 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
1e350 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
1e360 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
1e370 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
1e380 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
1e390 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
1e3a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
1e3b0 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
1e3c0 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
1e3d0 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
1e3e0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
1e3f0 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
1e400 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
1e410 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
1e420 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
1e430 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
1e440 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
1e450 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
1e460 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
1e470 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
1e480 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
1e490 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
1e4a0 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
1e4b0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
1e4c0 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
1e4d0 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
1e4e0 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
1e4f0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
1e500 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1e510 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
1e520 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
1e530 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1e540 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
1e550 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
1e560 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
1e570 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
1e580 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
1e590 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
1e5a0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1e5b0 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
1e5c0 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
1e5d0 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
1e5e0 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
1e5f0 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
1e600 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
1e610 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
1e620 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
1e630 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
1e640 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
1e650 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
1e660 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1e670 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
1e680 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
1e690 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
1e6a0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
1e6b0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1e6c0 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
1e6d0 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1e6e0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1e6f0 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1e700 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1e710 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1e720 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1e730 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1e740 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1e750 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1e760 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1e770 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1e780 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1e790 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1e7a0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1e7b0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1e7c0 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1e7d0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1e7e0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1e7f0 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1e800 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1e810 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1e820 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1e830 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1e840 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1e850 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1e860 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1e870 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1e880 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1e890 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e8a0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1e8b0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1e8c0 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1e8d0 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1e8e0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1e8f0 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1e900 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1e910 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1e920 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1e930 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1e940 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1e950 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1e960 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1e970 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1e980 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1e990 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1e9a0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1e9b0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1e9c0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1e9d0 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1e9e0 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1e9f0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1ea00 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1ea10 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1ea20 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1ea30 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1ea40 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1ea50 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1ea60 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1ea70 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1ea80 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1ea90 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1eaa0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1eab0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1eac0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1ead0 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1eae0 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1eaf0 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1eb00 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1eb10 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1eb20 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1eb30 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1eb40 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1eb50 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1eb60 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1eb70 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1eb80 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1eb90 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1eba0 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1ebb0 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1ebc0 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1ebd0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1ebe0 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1ebf0 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1ec00 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1ec10 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1ec20 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1ec30 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1ec40 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1ec50 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1ec60 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1ec70 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1ec80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1ec90 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1eca0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1ecb0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1ecc0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1ecd0 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1ece0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1ecf0 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1ed00 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1ed10 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1ed20 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1ed30 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1ed40 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1ed50 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1ed60 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1ed70 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1ed80 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1ed90 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1eda0 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1edb0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1edc0 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1edd0 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1ede0 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1edf0 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1ee00 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1ee10 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1ee20 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1ee30 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1ee40 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1ee50 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1ee60 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1ee70 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1ee80 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1ee90 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1eea0 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1eeb0 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1eec0 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1eed0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1eee0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1eef0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1ef00 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  rrmsg()]..*/.SQL
1ef10 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1ef20 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
1ef30 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1ef40 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
1ef50 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
1ef60 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
1ef70 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
1ef80 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
1ef90 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
1efa0 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
1efb0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
1efc0 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
1efd0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
1efe0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
1eff0 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
1f000 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
1f010 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
1f020 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1f030 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
1f040 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
1f050 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
1f060 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
1f070 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
1f080 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1f090 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1f0a0 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74  le(char **result
1f0b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f0c0 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74  EF: Formatted St
1f0d0 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75  ring Printing Fu
1f0e0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
1f0f0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
1f100 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20   work-alikes of 
1f110 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66  the "printf()" f
1f120 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f  amily of functio
1f130 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73  ns.** from the s
1f140 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1f150 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  y..** These rout
1f160 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64 20  ines understand 
1f170 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d 6d  most of the comm
1f180 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69 6e  on K&R formattin
1f190 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70 6c  g options,.** pl
1f1a0 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  us some addition
1f1b0 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64 20  al non-standard 
1f1c0 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c 65  formats, detaile
1f1d0 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74 65  d below..** Note
1f1e0 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74 68   that some of th
1f1f0 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20 66  e more obscure f
1f200 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1f210 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a 2a  s from recent.**
1f220 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e 64   C-library stand
1f230 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65 64  ards are omitted
1f240 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c 65   from this imple
1f250 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  mentation..**.**
1f260 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70   ^The sqlite3_mp
1f270 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69  rintf() and sqli
1f280 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72  te3_vmprintf() r
1f290 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68  outines write th
1f2a0 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69  eir.** results i
1f2b0 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
1f2c0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
1f2d0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20  3_malloc()]..** 
1f2e0 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  The strings retu
1f2f0 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77  rned by these tw
1f300 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c  o routines shoul
1f310 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64  d be.** released
1f320 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   by [sqlite3_fre
1f330 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75  e()].  ^Both rou
1f340 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a  tines return a.*
1f350 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
1f360 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1f370 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74  c()] is unable t
1f380 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67  o allocate enoug
1f390 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68  h.** memory to h
1f3a0 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e  old the resultin
1f3b0 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  g string..**.** 
1f3c0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e  ^(The sqlite3_sn
1f3d0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1f3e0 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22   is similar to "
1f3f0 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d  snprintf()" from
1f400 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64  .** the standard
1f410 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65   C library.  The
1f420 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74   result is writt
1f430 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62  en into the.** b
1f440 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61  uffer supplied a
1f450 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1f460 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a  ameter whose siz
1f470 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a  e is given by.**
1f480 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1f490 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20  eter. Note that 
1f4a0 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65  the order of the
1f4b0 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61  .** first two pa
1f4c0 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65  rameters is reve
1f4d0 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e  rsed from snprin
1f4e0 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73  tf().)^  This is
1f4f0 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61   an.** historica
1f500 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20  l accident that 
1f510 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20  cannot be fixed 
1f520 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1f530 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f  .** backwards co
1f540 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28  mpatibility.  ^(
1f550 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73  Note also that s
1f560 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1f570 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70  ).** returns a p
1f580 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75  ointer to its bu
1f590 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  ffer instead of 
1f5a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
1f5b0 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75   characters actu
1f5c0 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74  ally written int
1f5d0 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20  o the buffer.)^ 
1f5e0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a   We admit that.*
1f5f0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
1f600 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74  characters writt
1f610 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f  en would be a mo
1f620 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e  re useful return
1f630 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65  .** value but we
1f640 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74   cannot change t
1f650 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
1f660 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70  n of sqlite3_snp
1f670 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77  rintf().** now w
1f680 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20  ithout breaking 
1f690 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
1f6a0 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73  *.** ^As long as
1f6b0 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65   the buffer size
1f6c0 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e   is greater than
1f6d0 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73   zero, sqlite3_s
1f6e0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61  nprintf().** gua
1f6f0 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
1f700 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79   buffer is alway
1f710 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
1f720 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a  d.  ^The first.*
1f730 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20  * parameter "n" 
1f740 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a  is the total siz
1f750 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c  e of the buffer,
1f760 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65   including space
1f770 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f   for.** the zero
1f780 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f   terminator.  So
1f790 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72   the longest str
1f7a0 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20  ing that can be 
1f7b0 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72  completely.** wr
1f7c0 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d  itten will be n-
1f7d0 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  1 characters..**
1f7e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1f7f0 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  _vsnprintf() rou
1f800 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67  tine is a vararg
1f810 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c  s version of sql
1f820 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e  ite3_snprintf().
1f830 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1f840 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d  tines all implem
1f850 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  ent some additio
1f860 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a  nal formatting.*
1f870 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61  * options that a
1f880 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f  re useful for co
1f890 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73  nstructing SQL s
1f8a0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c  tatements..** Al
1f8b0 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70  l of the usual p
1f8c0 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69  rintf() formatti
1f8d0 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79  ng options apply
1f8e0 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20  .  In addition, 
1f8f0 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20  there.** is are 
1f900 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77 22  "%q", "%Q", "%w"
1f910 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
1f920 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
1f930 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
1f940 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
1f950 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
1f960 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
1f970 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
1f980 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
1f990 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
1f9a0 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
1f9b0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
1f9c0 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
1f9d0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
1f9e0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
1f9f0 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
1fa00 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
1fa10 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
1fa20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
1fa30 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
1fa40 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
1fa50 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
1fa60 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
1fa70 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
1fa80 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
1fa90 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
1faa0 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
1fab0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1fac0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1fad0 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
1fae0 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
1faf0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1fb00 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
1fb10 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
1fb20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
1fb30 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
1fb40 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1fb50 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1fb60 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1fb70 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1fb80 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1fb90 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
1fba0 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1fbb0 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1fbc0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1fbd0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1fbe0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1fbf0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
1fc00 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
1fc10 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
1fc20 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
1fc30 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
1fc40 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
1fc50 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
1fc60 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
1fc70 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1fc80 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1fc90 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1fca0 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
1fcb0 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
1fcc0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1fcd0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1fce0 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
1fcf0 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
1fd00 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
1fd10 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
1fd20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
1fd30 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
1fd40 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1fd50 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1fd60 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1fd70 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
1fd80 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
1fd90 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1fda0 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
1fdb0 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
1fdc0 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
1fdd0 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
1fde0 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
1fdf0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
1fe00 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
1fe10 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
1fe20 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
1fe30 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
1fe40 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
1fe50 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
1fe60 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
1fe70 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
1fe80 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
1fe90 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
1fea0 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
1feb0 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
1fec0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
1fed0 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
1fee0 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
1fef0 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
1ff00 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
1ff10 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
1ff20 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
1ff30 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
1ff40 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
1ff50 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
1ff60 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1ff70 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1ff80 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1ff90 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1ffa0 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
1ffb0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1ffc0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1ffd0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1ffe0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1fff0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
20000 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
20010 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
20020 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
20030 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
20040 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
20050 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
20060 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
20070 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
20080 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
20090 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74  The "%w" formatt
200a0 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c 69  ing option is li
200b0 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20 74  ke "%q" except t
200c0 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20 74  hat it expects t
200d0 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e 65  o.** be containe
200e0 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65 2d  d within double-
200f0 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20 6f  quotes instead o
20100 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 2c  f single quotes,
20110 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61 70   and it.** escap
20120 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71 75  es the double-qu
20130 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69 6e  ote character in
20140 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69 6e  stead of the sin
20150 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68 61  gle-quote.** cha
20160 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20 22  racter.)^  The "
20170 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %w" formatting o
20180 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64 65  ption is intende
20190 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e 73  d for safely ins
201a0 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65 20  erting.** table 
201b0 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 73  and column names
201c0 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75 63   into a construc
201d0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
201e0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22  t..**.** ^(The "
201f0 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f  %z" formatting o
20200 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
20210 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74   "%s" but with t
20220 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74  he.** addition t
20230 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74  hat after the st
20240 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65  ring has been re
20250 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e  ad and copied in
20260 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  to.** the result
20270 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  , [sqlite3_free(
20280 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  )] is called on 
20290 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
202a0 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .)^.*/.SQLITE_AP
202b0 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
202c0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
202d0 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45  ar*,...);.SQLITE
202e0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
202f0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
20300 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
20310 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
20320 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72  ar *sqlite3_snpr
20330 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
20340 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29  onst char*, ...)
20350 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
20360 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  r *sqlite3_vsnpr
20370 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63  intf(int,char*,c
20380 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c  onst char*, va_l
20390 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ist);../*.** CAP
203a0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
203b0 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74  location Subsyst
203c0 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  em.**.** The SQL
203d0 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68  ite core uses th
203e0 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e  ese three routin
203f0 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  es for all of it
20400 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61  s own.** interna
20410 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
20420 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65  ion needs. "Core
20430 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  " in the previou
20440 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f  s sentence.** do
20450 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f  es not include o
20460 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
20470 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70  specific VFS imp
20480 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68  lementation.  Th
20490 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53  e.** Windows VFS
204a0 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c   uses native mal
204b0 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
204c0 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74   for some operat
204d0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions..**.** ^The
204e0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
204f0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
20500 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
20510 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d   block.** of mem
20520 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62  ory at least N b
20530 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20  ytes in length, 
20540 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70  where N is the p
20550 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66  arameter..** ^If
20560 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
20570 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f  ) is unable to o
20580 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74  btain sufficient
20590 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c   free.** memory,
205a0 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55   it returns a NU
205b0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66  LL pointer.  ^If
205c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e   the parameter N
205d0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d   to.** sqlite3_m
205e0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
205f0 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  or negative then
20600 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
20610 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e  ) returns.** a N
20620 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
20630 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
20640 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75 74  malloc64(N) rout
20650 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20 6c  ine works just l
20660 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ike.** sqlite3_m
20670 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74 20  alloc(N) except 
20680 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e 73  that N is an uns
20690 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e 74  igned 64-bit int
206a0 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20  eger instead.** 
206b0 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d 62  of a signed 32-b
206c0 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a  it integer..**.*
206d0 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
206e0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
206f0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
20700 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
20710 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
20720 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
20730 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
20740 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
20750 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
20760 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
20770 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
20780 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
20790 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
207a0 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
207b0 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
207c0 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
207d0 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
207e0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
207f0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
20800 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
20810 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
20820 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
20830 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
20840 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
20850 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
20860 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
20870 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
20880 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
20890 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
208a0 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
208b0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
208c0 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
208d0 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
208e0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
208f0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
20900 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
20910 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
20920 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
20930 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
20940 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
20950 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
20960 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  oc()..**.** ^The
20970 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
20980 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (X,N) interface 
20990 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
209a0 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
209b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
209c0 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74  X to be at least
209d0 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66   N bytes..** ^If
209e0 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65 72   the X parameter
209f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
20a00 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20 61  loc(X,N).** is a
20a10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
20a20 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20  en its behavior 
20a30 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20  is identical to 
20a40 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
20a50 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a  e3_malloc(N)..**
20a60 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61 6d   ^If the N param
20a70 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
20a80 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73 20  realloc(X,N) is 
20a90 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
20aa0 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
20ab0 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
20ac0 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
20ad0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
20ae0 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c  free(X)..** ^sql
20af0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
20b00 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
20b10 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
20b20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
20b30 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
20b40 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
20b50 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
20b60 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69  t memory is avai
20b70 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
20b80 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
20b90 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
20ba0 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
20bb0 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
20bc0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
20bd0 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
20be0 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
20bf0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
20c00 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
20c10 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
20c20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
20c30 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
20c40 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
20c50 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72  3_realloc(X,N) r
20c60 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 20  eturns NULL and 
20c70 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20 74  N is positive, t
20c80 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f 72  hen the.** prior
20c90 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6e   allocation is n
20ca0 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20  ot freed..**.** 
20cb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  ^The sqlite3_rea
20cc0 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74 65  lloc64(X,N) inte
20cd0 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68 65  rfaces works the
20ce0 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c 69   same as.** sqli
20cf0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
20d00 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
20d10 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69 67  s a 64-bit unsig
20d20 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73 74  ned integer inst
20d30 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d 62  ead.** of a 32-b
20d40 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
20d50 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20 69  r..**.** ^If X i
20d60 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  s a memory alloc
20d70 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c 79  ation previously
20d80 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
20d90 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c  qlite3_malloc(),
20da0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
20db0 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33 5f  oc64(), sqlite3_
20dc0 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73 71  realloc(), or sq
20dd0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28  lite3_realloc64(
20de0 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  ), then.** sqlit
20df0 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
20e00 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  rns the size of 
20e10 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  that memory allo
20e20 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73 2e  cation in bytes.
20e30 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20 72  .** ^The value r
20e40 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
20e50 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67 68  e3_msize(X) migh
20e60 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  t be larger than
20e70 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f   the number.** o
20e80 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74 65  f bytes requeste
20e90 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c 6c  d when X was all
20ea0 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20 69  ocated.  ^If X i
20eb0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
20ec0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
20ed0 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e  _msize(X) return
20ee0 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70 6f  s zero.  If X po
20ef0 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69 6e  ints to somethin
20f00 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a 2a  g that is not.**
20f10 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
20f20 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
20f30 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70 6f  ion, or if it po
20f40 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65 72  ints to a former
20f50 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d 6f  ly.** valid memo
20f60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 68  ry allocation th
20f70 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e 20  at has now been 
20f80 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65 20  freed, then the 
20f90 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 73  behavior.** of s
20fa0 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20  qlite3_msize(X) 
20fb0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
20fc0 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66 75   possibly harmfu
20fd0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
20fe0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
20ff0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
21000 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  ), sqlite3_reall
21010 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  oc(),.** sqlite3
21020 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e 64  _malloc64(), and
21030 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
21040 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  64().** is alway
21050 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
21060 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
21070 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
21080 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
21090 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
210a0 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
210b0 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
210c0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
210d0 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
210e0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
210f0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
21100 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
21110 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
21120 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
21130 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
21140 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
21150 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
21160 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
21170 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
21180 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
21190 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
211a0 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
211b0 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
211c0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
211d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
211e0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
211f0 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
21200 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
21210 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
21220 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
21230 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
21240 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
21250 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
21260 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
21270 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
21280 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
21290 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
212a0 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
212b0 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
212c0 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
212d0 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
212e0 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
212f0 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
21300 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
21310 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
21320 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
21330 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
21340 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
21350 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
21360 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
21370 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
21380 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
21390 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
213a0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
213b0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
213c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
213d0 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
213e0 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
213f0 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
21400 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
21410 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
21420 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
21430 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
21440 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
21450 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
21460 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
21470 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
21480 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
21490 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
214a0 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
214b0 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
214c0 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
214d0 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
214e0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
214f0 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
21500 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
21510 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
21520 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
21530 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  c(int);.SQLITE_A
21540 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
21550 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65  _malloc64(sqlite
21560 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  3_uint64);.SQLIT
21570 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
21580 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
21590 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
215a0 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
215b0 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64  3_realloc64(void
215c0 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  *, sqlite3_uint6
215d0 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  4);.SQLITE_API v
215e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
215f0 28 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f  (void*);.SQLITE_
21600 41 50 49 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  API sqlite3_uint
21610 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  64 sqlite3_msize
21620 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
21630 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
21640 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
21650 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
21660 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
21670 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
21680 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
21690 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
216a0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
216b0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
216c0 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
216d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
216e0 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
216f0 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
21700 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
21710 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
21720 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
21730 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
21740 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
21750 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
21760 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
21770 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
21780 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
21790 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
217a0 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
217b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
217c0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
217d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
217e0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
217f0 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
21800 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
21810 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
21820 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
21830 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
21840 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
21850 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
21860 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
21870 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
21880 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
21890 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
218a0 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
218b0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
218c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
218d0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
218e0 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
218f0 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
21900 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
21910 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
21920 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
21930 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
21940 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
21950 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
21960 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
21970 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
21980 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
21990 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
219a0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
219b0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
219c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
219d0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
219e0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
219f0 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
21a00 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
21a10 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
21a20 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
21a30 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
21a40 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
21a50 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
21a60 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
21a70 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
21a80 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
21a90 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  d(void);.SQLITE_
21aa0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
21ab0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
21ac0 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
21ad0 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
21ae0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
21af0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
21b00 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
21b10 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
21b20 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
21b30 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
21b40 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
21b50 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
21b60 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
21b70 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
21b80 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
21b90 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
21ba0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
21bb0 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
21bc0 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
21bd0 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
21be0 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
21bf0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
21c00 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
21c10 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
21c20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
21c30 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
21c40 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
21c50 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
21c60 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
21c70 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
21c80 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
21c90 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
21ca0 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
21cb0 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
21cc0 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
21cd0 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
21ce0 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
21cf0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
21d00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
21d10 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
21d20 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
21d30 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
21d40 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
21d50 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
21d60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
21d70 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
21d80 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
21d90 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
21da0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
21db0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
21dc0 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
21dd0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
21de0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
21df0 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
21e00 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
21e10 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
21e20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
21e30 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
21e40 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
21e50 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
21e60 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
21e70 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
21e80 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
21e90 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
21ea0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
21eb0 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54  method..*/.SQLIT
21ec0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
21ed0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
21ee0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
21ef0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21f00 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
21f10 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
21f20 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
21f30 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
21f40 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69  his routine regi
21f50 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69  sters an authori
21f60 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74  zer callback wit
21f70 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a  h a particular.*
21f80 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
21f90 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65  ection], supplie
21fa0 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
21fb0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
21fc0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21fd0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
21fe0 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  as SQL statement
21ff0 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70  s are being comp
22000 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  iled.** by [sqli
22010 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
22020 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b  r its variants [
22030 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
22040 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
22050 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
22060 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
22070 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e  pare16_v2()].  ^
22080 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f  At various.** po
22090 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20  ints during the 
220a0 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63  compilation proc
220b0 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73  ess, as logic is
220c0 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a   being created.*
220d0 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72  * to perform var
220e0 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68  ious actions, th
220f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
22100 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
22110 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68   to.** see if th
22120 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20  ose actions are 
22130 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61  allowed.  ^The a
22140 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22150 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ck should.** ret
22160 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
22170 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74  to allow the act
22180 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e  ion, [SQLITE_IGN
22190 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77  ORE] to disallow
221a0 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63   the.** specific
221b0 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f   action but allo
221c0 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  w the SQL statem
221d0 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  ent to continue 
221e0 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65  to be.** compile
221f0 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  d, or [SQLITE_DE
22200 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65  NY] to cause the
22210 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74   entire SQL stat
22220 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72  ement to be.** r
22230 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20  ejected with an 
22240 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20  error.  ^If the 
22250 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22260 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ack returns.** a
22270 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74  ny value other t
22280 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  han [SQLITE_IGNO
22290 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  RE], [SQLITE_OK]
222a0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
222b0 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b  Y].** then the [
222c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
222d0 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c  v2()] or equival
222e0 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72  ent call that tr
222f0 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61  iggered.** the a
22300 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66  uthorizer will f
22310 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f  ail with an erro
22320 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a  r message..**.**
22330 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   When the callba
22340 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
22350 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61  TE_OK], that mea
22360 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  ns the operation
22370 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73  .** requested is
22380 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20   ok.  ^When the 
22390 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
223a0 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20   [SQLITE_DENY], 
223b0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
223c0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
223d0 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c   equivalent call
223e0 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20   that triggered 
223f0 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
22400 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68  r will fail with
22410 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
22420 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61  e explaining tha
22430 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64  t.** access is d
22440 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54  enied. .**.** ^T
22450 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
22460 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
22470 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
22480 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74   a copy of the t
22490 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
224a0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
224b0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
224c0 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68  ) interface. ^Th
224d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
224e0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  er.** to the cal
224f0 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
22500 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59  ger [SQLITE_COPY
22510 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20   | action code] 
22520 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
22530 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  * the particular
22540 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
22550 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74  thorized. ^The t
22560 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78  hird through six
22570 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  th parameters.**
22580 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
22590 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   are zero-termin
225a0 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
225b0 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
225c0 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20  onal.** details 
225d0 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e  about the action
225e0 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
225f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
22600 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
22610 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a  [SQLITE_READ].**
22620 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63   and the callbac
22630 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
22640 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
22650 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
22660 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65  statement] state
22670 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63  ment is construc
22680 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74  ted to substitut
22690 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75  e.** a NULL valu
226a0 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68  e in place of th
226b0 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  e table column t
226c0 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a  hat would have.*
226d0 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b  * been read if [
226e0 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62  SQLITE_OK] had b
226f0 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54  een returned.  T
22700 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  he [SQLITE_IGNOR
22710 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e  E].** return can
22720 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79   be used to deny
22730 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73   an untrusted us
22740 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64  er access to ind
22750 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d  ividual.** colum
22760 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a  ns of a table..*
22770 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
22780 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
22790 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65  _DELETE] and the
227a0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
227b0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e  s.** [SQLITE_IGN
227c0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44  ORE] then the [D
227d0 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e  ELETE] operation
227e0 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68   proceeds but th
227f0 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f  e.** [truncate o
22800 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20  ptimization] is 
22810 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c  disabled and all
22820 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65   rows are delete
22830 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a  d individually..
22840 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69  **.** An authori
22850 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e  zer is used when
22860 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22870 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a  e | preparing].*
22880 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
22890 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74   from an untrust
228a0 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e  ed source, to en
228b0 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51  sure that the SQ
228c0 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
228d0 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63  do not try to ac
228e0 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61  cess data they a
228f0 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74  re not allowed t
22900 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74  o see, or that t
22910 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72  hey do not.** tr
22920 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c  y to execute mal
22930 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74  icious statement
22940 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68  s that damage th
22950 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72  e database.  For
22960 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  .** example, an 
22970 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20  application may 
22980 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20  allow a user to 
22990 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a  enter arbitrary.
229a0 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66  ** SQL queries f
229b0 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79  or evaluation by
229c0 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75   a database.  Bu
229d0 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
229e0 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61  n does.** not wa
229f0 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62  nt the user to b
22a00 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61  e able to make a
22a10 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73  rbitrary changes
22a20 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62   to the.** datab
22a30 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69  ase.  An authori
22a40 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62  zer could then b
22a50 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77  e put in place w
22a60 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72  hile the.** user
22a70 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20  -entered SQL is 
22a80 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  being [sqlite3_p
22a90 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65  repare | prepare
22aa0 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c  d] that.** disal
22ab0 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20  lows everything 
22ac0 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20  except [SELECT] 
22ad0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
22ae0 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
22af0 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63  hat need to proc
22b00 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74  ess SQL from unt
22b10 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a  rusted sources.*
22b20 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e  * might also con
22b30 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72  sider lowering r
22b40 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75  esource limits u
22b50 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
22b60 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69  mit()].** and li
22b70 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  miting database 
22b80 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b  size using the [
22b90 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
22ba0 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61  [PRAGMA].** in a
22bb0 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67  ddition to using
22bc0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a   an authorizer..
22bd0 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73  **.** ^(Only a s
22be0 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72  ingle authorizer
22bf0 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65   can be in place
22c00 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63   on a database c
22c10 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20  onnection.** at 
22c20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61  a time.  Each ca
22c30 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65  ll to sqlite3_se
22c40 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65  t_authorizer ove
22c50 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72  rrides the.** pr
22c60 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20  evious call.)^  
22c70 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74  ^Disable the aut
22c80 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61  horizer by insta
22c90 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c  lling a NULL cal
22ca0 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75  lback..** The au
22cb0 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61  thorizer is disa
22cc0 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
22cd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
22ce0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
22cf0 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
22d00 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
22d10 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
22d20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22d30 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
22d40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
22d50 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  back..** Note th
22d60 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
22d70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
22d80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
22d90 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
22da0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
22db0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
22dc0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
22dd0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
22de0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57  agraph..**.** ^W
22df0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
22e00 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73  pare_v2()] is us
22e10 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20  ed to prepare a 
22e20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a  statement, the.*
22e30 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68  * statement migh
22e40 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64  t be re-prepared
22e50 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33   during [sqlite3
22e60 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20  _step()] due to 
22e70 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61  a .** schema cha
22e80 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  nge.  Hence, the
22e90 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
22ea0 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20  uld ensure that 
22eb0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61  the.** correct a
22ec0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
22ed0 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c  ck remains in pl
22ee0 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b  ace during the [
22ef0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
22f00 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61  .**.** ^Note tha
22f10 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  t the authorizer
22f20 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
22f30 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67  oked only during
22f40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
22f50 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
22f60 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72  ariants.  Author
22f70 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a  ization is not.*
22f80 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69  * performed duri
22f90 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61  ng statement eva
22fa0 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69  luation in [sqli
22fb0 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c  te3_step()], unl
22fc0 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64  ess.** as stated
22fd0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
22fe0 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69   paragraph, sqli
22ff0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b  te3_step() invok
23000 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  es.** sqlite3_pr
23010 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65  epare_v2() to re
23020 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
23030 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65  ent after a sche
23040 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51  ma change..*/.SQ
23050 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
23060 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
23070 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  zer(.  sqlite3*,
23080 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28  .  int (*xAuth)(
23090 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
230a0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
230b0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
230c0 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f  nst char*),.  vo
230d0 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b  id *pUserData.);
230e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
230f0 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74  : Authorizer Ret
23100 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  urn Codes.**.** 
23110 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
23120 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
23130 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
23140 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74  k function] must
23150 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65  .** return eithe
23160 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72  r [SQLITE_OK] or
23170 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77   one of these tw
23180 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f  o constants in o
23190 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61  rder.** to signa
231a0 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72  l SQLite whether
231b0 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69   or not the acti
231c0 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e  on is permitted.
231d0 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71    See the.** [sq
231e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
231f0 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65  izer | authorize
23200 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d  r documentation]
23210 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
23220 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
23230 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
23240 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73  SQLITE_IGNORE is
23250 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20   also used as a 
23260 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c 75  [conflict resolu
23270 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65  tion mode].** re
23280 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65 20  turned from the 
23290 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
232a0 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
232b0 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
232c0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
232d0 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
232e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
232f0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
23300 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23310 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
23320 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
23330 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
23340 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
23350 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23360 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
23370 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
23380 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
23390 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
233a0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
233b0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
233c0 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
233d0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
233e0 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
233f0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
23400 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
23410 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
23420 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
23430 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
23440 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
23450 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
23460 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
23470 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
23480 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
23490 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
234a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
234b0 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
234c0 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
234d0 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
234e0 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
234f0 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
23500 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
23510 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
23520 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
23530 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
23540 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
23550 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
23560 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
23570 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
23580 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
23590 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
235a0 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
235b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
235c0 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
235d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
235e0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
235f0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
23600 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
23610 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
23620 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
23630 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
23640 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
23650 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
23660 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
23670 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
23680 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
23690 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
236a0 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
236b0 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
236c0 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
236d0 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
236e0 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
236f0 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
23700 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
23710 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
23720 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23730 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23740 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
23750 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
23760 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
23770 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
23780 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
23790 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
237a0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
237b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
237c0 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
237d0 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
237e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
237f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23800 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23810 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
23820 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
23830 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
23840 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23850 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23860 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
23870 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
23880 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
23890 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
238a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
238b0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
238c0 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
238d0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
238e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
238f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23900 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
23910 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
23920 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
23930 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
23950 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
23960 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
23970 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
23980 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
23990 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
239a0 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
239b0 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
239c0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
239d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
239e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
239f0 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
23a00 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
23a10 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
23a20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23a30 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
23a40 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
23a50 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
23a60 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
23a70 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
23a80 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
23a90 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
23aa0 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
23ab0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
23ac0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
23ad0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
23ae0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
23af0 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
23b00 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
23b10 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
23b20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
23b30 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
23b40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
23b50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
23b60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23b70 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
23b80 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
23b90 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
23ba0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
23bb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23bc0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
23bd0 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
23be0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
23bf0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
23c00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
23c10 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
23c20 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
23c30 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
23c40 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
23c50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23c60 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
23c70 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
23c80 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
23c90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
23ca0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23cb0 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
23cc0 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
23cd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23ce0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
23cf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23d00 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
23d10 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
23d20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
23d30 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
23d40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23d50 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
23d60 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
23d70 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
23d80 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
23d90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23da0 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
23db0 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
23dc0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
23dd0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
23de0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23df0 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
23e00 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
23e10 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
23e20 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
23e30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
23e40 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
23e50 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
23e60 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
23e70 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
23e80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
23e90 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
23ea0 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
23eb0 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
23ec0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
23ed0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
23ee0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
23ef0 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
23f00 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
23f10 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
23f20 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
23f30 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
23f40 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
23f50 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
23f60 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
23f70 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
23f80 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
23f90 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
23fa0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
23fb0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
23fc0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
23fd0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
23fe0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
23ff0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
24000 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
24010 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
24020 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
24030 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
24040 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
24050 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
24060 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
24070 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
24080 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
24090 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
240a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
240b0 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
240c0 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
240d0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
240e0 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
240f0 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
24100 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
24110 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
24120 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
24130 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
24140 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
24150 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
24160 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
24170 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
24180 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24190 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20 20  TE_RECURSIVE    
241a0 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a 20          33   /* 
241b0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
241c0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
241d0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
241e0 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20  EF: Tracing And 
241f0 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69  Profiling Functi
24200 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ons.** METHOD: s
24210 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65  qlite3.**.** The
24220 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
24230 64 65 70 72 65 63 61 74 65 64 2e 20 55 73 65 20  deprecated. Use 
24240 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  the [sqlite3_tra
24250 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  ce_v2()] interfa
24260 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f 66  ce.** instead of
24270 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64 65   the routines de
24280 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a 2a  scribed here..**
24290 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
242a0 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
242b0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
242c0 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
242d0 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
242e0 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
242f0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
24300 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
24310 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
24320 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
24330 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
24340 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
24350 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
24360 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
24370 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
24380 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
24390 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
243a0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
243b0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
243c0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
243d0 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
243e0 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
243f0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
24400 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
24410 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
24420 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
24430 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
24440 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
24450 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
24460 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
24470 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
24480 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
24490 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
244a0 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
244b0 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
244c0 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
244d0 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
244e0 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  r.)^.**.** The [
244f0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
24500 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
24510 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e  -time option can
24520 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69   be used to limi
24530 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20  t.** the length 
24540 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
24550 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69  ter] expansion i
24560 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  n the output of 
24570 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e  sqlite3_trace().
24580 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
24590 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
245a0 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
245b0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
245c0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
245d0 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
245e0 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
245f0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
24600 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
24610 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
24620 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
24630 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
24640 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
24650 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
24660 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
24670 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
24680 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
24690 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
246a0 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
246b0 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
246c0 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
246d0 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
246e0 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
246f0 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
24700 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
24710 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
24720 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
24730 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
24740 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
24750 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
24760 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
24770 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
24780 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
24790 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
247a0 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
247b0 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
247c0 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
247d0 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
247e0 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
247f0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
24800 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
24810 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
24820 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
24830 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73  PRECATED void *s
24840 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
24850 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
24860 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
24870 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
24880 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
24890 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
248a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
248b0 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
248c0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
248d0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
248e0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
248f0 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
24900 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24910 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74 20  SQL Trace Event 
24920 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
24930 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45 0a  S: SQLITE_TRACE.
24940 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
24950 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20 63  tants identify c
24960 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74 73  lasses of events
24970 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f 6e   that can be mon
24980 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67 20  itored.** using 
24990 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72 61  the [sqlite3_tra
249a0 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e 67  ce_v2()] tracing
249b0 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68 69   logic.  The thi
249c0 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  rd argument.** t
249d0 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
249e0 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52 2d  _v2()] is an OR-
249f0 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f  ed combination o
24a00 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  f one or more of
24a10 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** the followin
24a20 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e 54  g constants.  ^T
24a30 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
24a40 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20 63  t to the trace c
24a50 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e  allback.** is on
24a60 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
24a70 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a  ng constants..**
24a80 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67 20  .** New tracing 
24a90 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65  constants may be
24aa0 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
24ab0 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a   releases..**.**
24ac0 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
24ad0 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67 75  ck has four argu
24ae0 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63 6b  ments: xCallback
24af0 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54  (T,C,P,X)..** ^T
24b00 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69 73  he T argument is
24b10 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74 65   one of the inte
24b20 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20 61  ger type codes a
24b30 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43 20  bove..** ^The C 
24b40 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f  argument is a co
24b50 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78  py of the contex
24b60 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  t pointer passed
24b70 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f   in as the.** fo
24b80 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
24b90 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f   [sqlite3_trace_
24ba0 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50 20  v2()]..** The P 
24bb0 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73 20  and X arguments 
24bc0 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68 6f  are pointers who
24bd0 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70 65  se meanings depe
24be0 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c  nd on T..**.** <
24bf0 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
24c00 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64 74  TRACE_STMT]] <dt
24c10 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54  >SQLITE_TRACE_ST
24c20 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  MT</dt>.** <dd>^
24c30 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
24c40 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69 73  STMT callback is
24c50 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
24c60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24c70 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67 69  nt.** first begi
24c80 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 70  ns running and p
24c90 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65 72  ossibly at other
24ca0 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74 68   times during th
24cb0 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20 6f  e.** execution o
24cc0 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  f the prepared s
24cd0 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20 61  tatement, such a
24ce0 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20 6f  s at the start o
24cf0 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67 65  f each.** trigge
24d00 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e 54  r subprogram. ^T
24d10 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
24d20 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
24d30 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
24d40 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65 20  tatement]. ^The 
24d50 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  X argument is a 
24d60 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72  pointer to a str
24d70 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ing which.** is 
24d80 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20 53  the unexpanded S
24d90 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20 70  QL text of the p
24da0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24db0 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d 6d  t or an SQL comm
24dc0 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ent .** that ind
24dd0 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f 63  icates the invoc
24de0 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67 67  ation of a trigg
24df0 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62 61  er.  ^The callba
24e00 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a 2a  ck can compute.*
24e10 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74 20  * the same text 
24e20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 20  that would have 
24e30 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62 79  been returned by
24e40 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
24e50 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a 2a  ite3_trace()].**
24e60 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75 73   interface by us
24e70 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d 65  ing the X argume
24e80 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e 73  nt when X begins
24e90 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20 69   with "--" and i
24ea0 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  nvoking.** [sqli
24eb0 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c  te3_expanded_sql
24ec0 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e 0a  (P)] otherwise..
24ed0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54  **.** [[SQLITE_T
24ee0 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c  RACE_PROFILE]] <
24ef0 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
24f00 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20  PROFILE</dt>.** 
24f10 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
24f20 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c  RACE_PROFILE cal
24f30 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20 61  lback provides a
24f40 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68 65  pproximately the
24f50 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61   same.** informa
24f60 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76 69  tion as is provi
24f70 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ded by the [sqli
24f80 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20 63  te3_profile()] c
24f90 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65  allback..** ^The
24fa0 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
24fb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
24fc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24fd0 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ent] and the.** 
24fe0 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  X argument point
24ff0 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69 6e  s to a 64-bit in
25000 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 74  teger which is t
25010 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66 0a  he estimated of.
25020 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
25030 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61 74   nanosecond that
25040 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
25050 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
25060 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c  run..** ^The SQL
25070 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
25080 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  E callback is in
25090 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 73  voked when the s
250a0 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65  tatement finishe
250b0 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  s..**.** [[SQLIT
250c0 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c 64  E_TRACE_ROW]] <d
250d0 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  t>SQLITE_TRACE_R
250e0 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e  OW</dt>.** <dd>^
250f0 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  An SQLITE_TRACE_
25100 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ROW callback is 
25110 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
25120 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
25130 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61 74  tatement generat
25140 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20  es a single row 
25150 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a 20  of result.  .** 
25160 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
25170 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
25180 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
25190 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
251a0 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 69  .** X argument i
251b0 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s unused..**.** 
251c0 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  [[SQLITE_TRACE_C
251d0 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LOSE]] <dt>SQLIT
251e0 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f 64  E_TRACE_CLOSE</d
251f0 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51  t>.** <dd>^An SQ
25200 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
25210 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
25220 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74 61  oked when a data
25230 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
25240 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54  on closes..** ^T
25250 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73  he P argument is
25260 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
25270 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
25280 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a  ection] object.*
25290 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67 75  * and the X argu
252a0 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a  ment is unused..
252b0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
252c0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
252d0 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30 31  _STMT       0x01
252e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
252f0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20 20  TRACE_PROFILE   
25300 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53 51   0x02.#define SQ
25310 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 20  LITE_TRACE_ROW  
25320 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66 69        0x04.#defi
25330 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
25340 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38 0a  CLOSE      0x08.
25350 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25360 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b 0a   SQL Trace Hook.
25370 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
25380 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e3.**.** ^The sq
25390 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 44  lite3_trace_v2(D
253a0 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,M,X,P) interfac
253b0 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74 72  e registers a tr
253c0 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ace callback.** 
253d0 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69 6e  function X again
253e0 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  st [database con
253f0 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69 6e  nection] D, usin
25400 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b 20  g property mask 
25410 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78 74  M.** and context
25420 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49 66   pointer P.  ^If
25430 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20   the X callback 
25440 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69 66  is.** NULL or if
25450 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20 7a   the M mask is z
25460 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69 6e  ero, then tracin
25470 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  g is disabled.  
25480 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65 6e  The.** M argumen
25490 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20  t should be the 
254a0 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63 6f  bitwise OR-ed co
254b0 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
254c0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53 51  zero or more [SQ
254d0 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e 73  LITE_TRACE] cons
254e0 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61  tants..**.** ^Ea
254f0 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65  ch call to eithe
25500 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  r sqlite3_trace(
25510 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72 61  ) or sqlite3_tra
25520 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64 65  ce_v2() override
25530 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29 20  s .** (cancels) 
25540 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73 20  any prior calls 
25550 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  to sqlite3_trace
25560 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72  () or sqlite3_tr
25570 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  ace_v2()..**.** 
25580 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b 20  ^The X callback 
25590 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  is invoked whene
255a0 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20 65  ver any of the e
255b0 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65 64  vents identified
255c0 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f   by .** mask M o
255d0 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74 65  ccur.  ^The inte
255e0 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ger return value
255f0 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62 61   from the callba
25600 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79 0a  ck is currently.
25610 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f 75  ** ignored, thou
25620 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61 6e  gh this may chan
25630 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ge in future rel
25640 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63 6b  eases.  Callback
25650 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
25660 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ons should retur
25670 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72 65  n zero to ensure
25680 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69 62   future compatib
25690 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  ility..**.** ^A 
256a0 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 69  trace callback i
256b0 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 66  s invoked with f
256c0 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20 63  our arguments: c
256d0 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29  allback(T,C,P,X)
256e0 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67 75  ..** ^The T argu
256f0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 74  ment is one of t
25700 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
25710 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20 74  ].** constants t
25720 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20 74  o indicate why t
25730 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73 20  he callback was 
25740 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65  invoked..** ^The
25750 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   C argument is a
25760 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
25770 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  text pointer..**
25780 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72 67   The P and X arg
25790 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e 74  uments are point
257a0 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e  ers whose meanin
257b0 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a  gs depend on T..
257c0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
257d0 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e 74  3_trace_v2() int
257e0 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64  erface is intend
257f0 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74 68  ed to replace th
25800 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
25810 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
25820 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73 71  trace()] and [sq
25830 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d  lite3_profile()]
25840 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68 0a  , both of which.
25850 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74 65  ** are deprecate
25860 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
25870 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61   int sqlite3_tra
25880 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  ce_v2(.  sqlite3
25890 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75 4d  *,.  unsigned uM
258a0 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61 6c  ask,.  int(*xCal
258b0 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64 2c  lback)(unsigned,
258c0 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64  void*,void*,void
258d0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74 78  *),.  void *pCtx
258e0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
258f0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
25900 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
25910 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
25920 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
25930 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
25940 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
25950 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
25960 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
25970 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
25980 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
25990 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
259a0 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
259b0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
259c0 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
259d0 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
259e0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
259f0 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
25a00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
25a10 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
25a20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
25a30 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
25a40 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
25a50 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
25a60 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
25a70 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
25a80 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
25a90 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
25aa0 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
25ab0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
25ac0 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
25ad0 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
25ae0 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
25af0 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
25b00 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
25b10 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
25b20 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
25b30 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
25b40 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
25b50 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
25b60 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
25b70 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
25b80 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
25b90 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
25ba0 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
25bb0 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
25bc0 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
25bd0 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
25be0 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
25bf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
25c00 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
25c10 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
25c20 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
25c30 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
25c40 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
25c50 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
25c60 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
25c70 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
25c80 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
25c90 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
25ca0 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
25cb0 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
25cc0 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
25cd0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
25ce0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
25cf0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
25d00 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
25d10 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
25d20 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
25d30 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
25d40 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
25d50 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
25d60 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
25d70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
25d80 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
25d90 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
25da0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
25db0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
25dc0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
25dd0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
25de0 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
25df0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
25e00 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
25e10 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
25e20 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
25e30 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
25e40 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
25e50 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
25e60 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
25e70 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
25e80 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
25e90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
25ea0 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
25eb0 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
25ec0 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
25ed0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
25ee0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25ef0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
25f00 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
25f10 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  ion.** CONSTRUCT
25f20 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
25f30 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
25f40 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
25f50 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
25f60 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
25f70 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
25f80 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
25f90 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
25fa0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
25fb0 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
25fc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
25fd0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
25fe0 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
25ff0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
26000 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
26010 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
26020 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
26030 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
26040 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
26050 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
26060 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
26070 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
26080 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
26090 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
260a0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
260b0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
260c0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
260d0 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
260e0 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
260f0 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
26100 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
26110 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
26120 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
26130 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
26140 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
26150 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
26160 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
26170 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
26180 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
26190 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
261a0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
261b0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
261c0 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
261d0 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
261e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
261f0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
26200 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
26210 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
26220 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
26230 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
26240 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
26250 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
26260 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
26270 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
26280 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
26290 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69  ault encoding wi
262a0 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20  ll be UTF-8 for 
262b0 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65  databases create
262c0 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  d using.** sqlit
262d0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
262e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
262f0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
26300 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62  coding for datab
26310 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  ases.** created 
26320 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  using sqlite3_op
26330 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55  en16() will be U
26340 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
26350 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
26360 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
26370 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
26380 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
26390 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
263a0 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
263b0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
263c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
263d0 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
263e0 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
263f0 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
26400 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
26410 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
26420 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
26430 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
26440 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
26450 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
26460 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
26470 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
26480 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
26490 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
264a0 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
264b0 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
264c0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
264d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
264e0 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
264f0 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
26500 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
26510 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
26520 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
26530 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
26540 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
26550 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
26560 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
26570 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
26580 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
26590 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
265a0 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
265b0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
265c0 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
265d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
265e0 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
265f0 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
26600 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
26610 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
26620 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
26630 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
26640 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
26650 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
26660 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
26670 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
26680 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
26690 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
266a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
266b0 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
266c0 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
266d0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
266e0 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
266f0 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
26700 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
26710 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
26720 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
26730 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
26740 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
26750 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
26760 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
26770 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
26780 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
26790 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
267a0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
267b0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
267c0 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
267d0 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
267e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
267f0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
26800 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
26810 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
26820 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
26830 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
26840 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
26850 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
26860 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
26870 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
26880 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
26890 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
268a0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
268b0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
268c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
268d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
268e0 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
268f0 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
26900 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
26910 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
26920 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
26930 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
26940 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
26950 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
26960 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
26970 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
26980 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
26990 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
269a0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
269b0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
269c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
269d0 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
269e0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
269f0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
26a00 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
26a10 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
26a20 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
26a30 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
26a40 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
26a50 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
26a60 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
26a70 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
26a80 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
26a90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
26aa0 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
26ab0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
26ac0 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
26ad0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
26ae0 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
26af0 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
26b00 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
26b10 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
26b20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
26b30 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
26b40 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
26b50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
26b60 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
26b70 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
26b80 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
26b90 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
26ba0 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
26bb0 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
26bc0 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
26bd0 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
26be0 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
26bf0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
26c00 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
26c10 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
26c20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26c30 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
26c40 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
26c50 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
26c60 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
26c70 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
26c80 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
26c90 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
26ca0 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
26cb0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
26cc0 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
26cd0 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
26ce0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
26cf0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
26d00 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
26d10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26d20 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
26d30 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
26d40 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
26d50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
26d60 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
26d70 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
26d80 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
26d90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
26da0 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
26db0 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
26dc0 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
26dd0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
26de0 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
26df0 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
26e00 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
26e10 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
26e20 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
26e30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
26e40 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
26e50 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
26e60 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
26e70 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
26e80 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
26e90 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
26ea0 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
26eb0 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
26ec0 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
26ed0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
26ee0 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
26ef0 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
26f00 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
26f10 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
26f20 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
26f30 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
26f40 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
26f50 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
26f60 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
26f70 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
26f80 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
26f90 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
26fa0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
26fb0 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
26fc0 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
26fd0 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
26fe0 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
26ff0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
27000 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
27010 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
27020 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
27030 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
27040 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
27050 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
27060 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
27070 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
27080 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
27090 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
270a0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
270b0 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
270c0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
270d0 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
270e0 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
270f0 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
27100 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
27110 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
27120 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
27130 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
27140 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
27150 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
27160 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
27170 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
27180 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
27190 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
271a0 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
271b0 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
271c0 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
271d0 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
271e0 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
271f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
27200 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
27210 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
27220 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
27230 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
27240 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
27250 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
27260 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
27270 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
27280 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
27290 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
272a0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
272b0 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
272c0 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
272d0 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
272e0 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
272f0 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
27300 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
27310 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
27320 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
27330 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
27340 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
27350 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
27360 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
27370 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
27380 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
27390 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
273a0 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
273b0 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
273c0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
273d0 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
273e0 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
273f0 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
27400 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
27410 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
27420 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
27430 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
27440 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
27450 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
27460 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
27470 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
27480 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
27490 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
274a0 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
274b0 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
274c0 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
274d0 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
274e0 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
274f0 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
27500 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
27510 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
27520 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
27530 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
27540 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
27550 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
27560 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
27570 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
27580 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
27590 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
275a0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
275b0 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
275c0 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64  h. .** ^(On wind
275d0 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
275e0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
275f0 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
27600 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
27610 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
27620 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  "C:").)^.**.** [
27630 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
27640 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
27650 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
27660 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
27670 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
27680 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
27690 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
276a0 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
276b0 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
276c0 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
276d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
276e0 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74  ** SQLite and it
276f0 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65  s built-in [VFSe
27700 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  s] interpret the
27710 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  .** following qu
27720 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
27730 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
27740 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
27750 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
27760 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
27770 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
27780 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
27790 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
277a0 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
277b0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
277c0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
277d0 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
277e0 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
277f0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27800 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
27810 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
27820 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
27830 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
27840 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
27850 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
27860 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
27870 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
27880 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
27890 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
278a0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
278b0 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
278c0 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
278d0 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
278e0 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
278f0 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
27900 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
27910 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
27920 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
27930 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
27940 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
27950 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
27960 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
27970 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
27980 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
27990 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
279a0 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
279b0 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
279c0 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
279d0 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
279e0 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
279f0 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
27a00 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
27a10 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
27a20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
27a30 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
27a40 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
27a50 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
27a60 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
27a70 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
27a80 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
27a90 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
27aa0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
27ab0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
27ac0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
27ad0 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
27ae0 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
27af0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
27b00 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
27b10 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
27b20 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
27b30 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
27b40 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
27b50 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
27b60 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
27b70 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
27b80 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
27b90 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
27ba0 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
27bb0 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
27bc0 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
27bd0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
27be0 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
27bf0 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
27c00 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
27c10 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
27c20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
27c30 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
27c40 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
27c50 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
27c60 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
27c70 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
27c80 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
27c90 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
27ca0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
27cb0 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
27cc0 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
27cd0 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
27ce0 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
27cf0 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
27d00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
27d10 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
27d20 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
27d30 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
27d40 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
27d50 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
27d60 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
27d70 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
27d80 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
27d90 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
27da0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
27db0 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
27dc0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
27dd0 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
27de0 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
27df0 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
27e00 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
27e10 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
27e20 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
27e30 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
27e40 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
27e50 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
27e60 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
27e70 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
27e80 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
27e90 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
27ea0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
27eb0 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
27ec0 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
27ed0 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
27ee0 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
27ef0 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
27f00 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
27f10 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
27f20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
27f30 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
27f40 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
27f50 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a  DCACHE flag..**.
27f60 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77  **  <li> <b>psow
27f70 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20  </b>: ^The psow 
27f80 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61  parameter indica
27f90 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e  tes whether or n
27fa0 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70  ot the.**     [p
27fb0 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
27fc0 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65  te] property doe
27fd0 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70  s or does not ap
27fe0 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ply to the.**   
27ff0 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20    storage media 
28000 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74  on which the dat
28010 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64  abase file resid
28020 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  es..**.**  <li> 
28030 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e  <b>nolock</b>: ^
28040 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d  The nolock param
28050 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
28060 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  n query paramete
28070 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69  r.**     which i
28080 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66  f set disables f
28090 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72  ile locking in r
280a0 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20  ollback journal 
280b0 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20  modes.  This.** 
280c0 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f      is useful fo
280d0 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61  r accessing a da
280e0 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65  tabase on a file
280f0 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73  system that does
28100 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70   not.**     supp
28110 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61  ort locking.  Ca
28120 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65  ution:  Database
28130 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68   corruption migh
28140 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a  t result if two.
28150 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70  **     or more p
28160 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74  rocesses write t
28170 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
28180 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20  ase and any one 
28190 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20  of those.**     
281a0 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e  processes uses n
281b0 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20  olock=1..**.**  
281c0 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c  <li> <b>immutabl
281d0 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75  e</b>: ^The immu
281e0 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20  table parameter 
281f0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
28200 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65  ry.**     parame
28210 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74  ter that indicat
28220 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  es that the data
28230 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f  base file is sto
28240 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65  red on.**     re
28250 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20  ad-only media.  
28260 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20  ^When immutable 
28270 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61  is set, SQLite a
28280 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
28290 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20  **     database 
282a0 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63  file cannot be c
282b0 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20  hanged, even by 
282c0 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68  a process with h
282d0 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69  igher.**     pri
282e0 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74  vilege, and so t
282f0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
28300 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20  pened read-only 
28310 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a  and all locking.
28320 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67  **     and chang
28330 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64  e detection is d
28340 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f  isabled.  Cautio
28350 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69  n: Setting the i
28360 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  mmutable.**     
28370 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61  property on a da
28380 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
28390 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68   does in fact ch
283a0 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a  ange can result.
283b0 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72  **     in incorr
283c0 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  ect query result
283d0 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  s and/or [SQLITE
283e0 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73  _CORRUPT] errors
283f0 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73  ..**     See als
28400 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  o: [SQLITE_IOCAP
28410 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20  _IMMUTABLE]..** 
28420 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a        .** </ul>.
28430 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
28440 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
28450 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
28460 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
28470 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
28480 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
28490 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
284a0 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
284b0 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
284c0 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
284d0 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
284e0 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
284f0 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
28500 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
28510 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
28520 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
28530 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
28540 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
28550 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
28560 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
28570 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
28580 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
28590 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
285a0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
285b0 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
285c0 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
285d0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
285e0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
285f0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
28600 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
28610 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
28620 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
28630 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
28640 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
28650 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
28660 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
28670 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
28680 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
28690 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
286a0 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
286b0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
286c0 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
286d0 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
286e0 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
286f0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
28700 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
28710 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
28720 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
28730 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
28740 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
28750 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
28760 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
28770 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
28780 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
28790 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
287a0 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
287b0 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
287c0 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
287d0 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
287e0 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
287f0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
28800 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
28810 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
28820 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
28830 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
28840 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
28850 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
28860 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
28870 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
28880 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
28890 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
288a0 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
288b0 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
288c0 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
288d0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
288e0 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
288f0 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
28900 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
28910 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
28920 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
28930 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
28940 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
28950 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
28960 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
28970 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
28980 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
28990 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
289a0 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
289b0 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
289c0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
289d0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
289e0 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c  ?vfs=unix-dotfil
289f0 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  e <td>.**       
28a00 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
28a10 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
28a20 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
28a30 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74  al VFS "unix-dot
28a40 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20  file".**        
28a50 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d    that uses dot-
28a60 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  files in place o
28a70 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79  f posix advisory
28a80 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72   locking..** <tr
28a90 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
28aa0 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
28ab0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
28ac0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
28ad0 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
28ae0 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
28af0 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
28b00 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
28b10 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
28b20 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
28b30 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
28b40 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
28b50 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
28b60 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
28b70 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
28b80 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
28b90 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
28ba0 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
28bb0 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
28bc0 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
28bd0 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
28be0 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
28bf0 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
28c00 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
28c10 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
28c20 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
28c30 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
28c40 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
28c50 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
28c60 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
28c70 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
28c80 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
28c90 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
28ca0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
28cb0 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
28cc0 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
28cd0 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
28ce0 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
28cf0 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
28d00 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
28d10 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
28d20 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
28d30 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
28d40 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
28d50 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
28d60 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
28d70 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
28d80 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
28d90 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
28da0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
28db0 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
28dc0 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
28dd0 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
28de0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
28df0 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
28e00 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
28e10 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
28e20 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
28e30 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
28e40 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
28e50 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
28e60 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
28e70 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
28e80 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
28e90 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
28ea0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
28eb0 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
28ec0 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
28ed0 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
28ee0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
28ef0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
28f00 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
28f10 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
28f20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
28f30 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
28f40 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
28f50 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
28f60 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
28f70 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
28f80 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ry].*/.SQLITE_AP
28f90 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
28fa0 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
28fb0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
28fc0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
28fd0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
28fe0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
28ff0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
29000 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
29010 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
29020 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
29030 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
29040 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
29050 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
29060 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
29070 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
29080 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
29090 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
290a0 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  dle */.);.SQLITE
290b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
290c0 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
290d0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
290e0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
290f0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
29100 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
29110 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
29120 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
29130 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
29140 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
29150 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
29160 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
29170 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
29180 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
29190 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
291a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
291b0 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
291c0 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
291d0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
291e0 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
291f0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
29200 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
29210 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
29220 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
29230 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
29240 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
29250 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
29260 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
29270 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
29280 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
29290 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
292a0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
292b0 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
292c0 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
292d0 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
292e0 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
292f0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
29300 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
29310 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
29320 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
29330 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
29340 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
29350 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
29360 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
29370 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
29380 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
29390 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
293a0 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
293b0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
293c0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
293d0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
293e0 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
293f0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
29400 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
29410 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
29420 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
29430 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
29440 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
29450 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
29460 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
29470 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
29480 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
29490 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
294a0 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
294b0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
294c0 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
294d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
294e0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
294f0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
29500 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
29510 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
29520 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
29530 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
29540 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
29550 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
29560 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
29570 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
29580 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
29590 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
295a0 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
295b0 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
295c0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
295d0 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
295e0 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
295f0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
29600 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
29610 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
29620 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
29630 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
29640 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
29650 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
29660 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
29670 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
29680 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
29690 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
296a0 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
296b0 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
296c0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
296d0 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
296e0 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
296f0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
29700 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
29710 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
29720 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
29730 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
29740 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
29750 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
29760 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
29770 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
29780 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
29790 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
297a0 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
297b0 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
297c0 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
297d0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
297e0 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
297f0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
29800 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
29810 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
29820 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
29830 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
29840 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
29850 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
29860 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
29870 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
29880 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
29890 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
298a0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
298b0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
298c0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
298d0 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
298e0 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
298f0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
29900 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
29910 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
29920 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
29930 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
29940 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
29950 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
29960 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
29970 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
29980 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
29990 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
299a0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
299b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
299c0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
299d0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
299e0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
299f0 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53  char *zParam);.S
29a00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
29a10 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
29a20 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
29a30 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
29a40 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
29a50 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41  fault);.SQLITE_A
29a60 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
29a70 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
29a80 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  64(const char*, 
29a90 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
29aa0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f  ite3_int64);.../
29ab0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
29ac0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
29ad0 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f  essages.** METHO
29ae0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
29af0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
29b00 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41  cent sqlite3_* A
29b10 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  PI call associat
29b20 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74  ed with .** [dat
29b30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29b40 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  ] D failed, then
29b50 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   the sqlite3_err
29b60 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63  code(D) interfac
29b70 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  e.** returns the
29b80 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
29b90 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
29ba0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
29bb0 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49   for that.** API
29bc0 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65   call..** If the
29bd0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
29be0 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73   call was succes
29bf0 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  sful,.** then th
29c00 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
29c10 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63  rom sqlite3_errc
29c20 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
29c30 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
29c40 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
29c50 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
29c60 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
29c70 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
29c80 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
29c90 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
29ca0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
29cb0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
29cc0 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
29cd0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
29ce0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29cf0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
29d00 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
29d10 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
29d20 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
29d30 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
29d40 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
29d50 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
29d60 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
29d70 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
29d80 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
29d90 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
29da0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
29db0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
29dc0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
29dd0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
29de0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
29df0 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
29e00 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
29e10 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
29e20 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
29e30 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
29e40 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
29e50 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
29e60 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
29e70 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
29e80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
29e90 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  str() interface 
29ea0 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c  returns the Engl
29eb0 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
29ec0 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69  t.** that descri
29ed0 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20  bes the [result 
29ee0 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e  code], as UTF-8.
29ef0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
29f00 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
29f10 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
29f20 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
29f30 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20  lly.** and must 
29f40 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20  not be freed by 
29f50 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
29f60 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  ^..**.** When th
29f70 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
29f80 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
29f90 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
29fa0 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
29fb0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
29fc0 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
29fd0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
29fe0 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
29ff0 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
2a000 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
2a010 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
2a020 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
2a030 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
2a040 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
2a050 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
2a060 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
2a070 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
2a080 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
2a090 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
2a0a0 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
2a0b0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
2a0c0 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
2a0d0 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
2a0e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2a0f0 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
2a100 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
2a110 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
2a120 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
2a130 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
2a140 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
2a150 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
2a160 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
2a170 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
2a180 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
2a190 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
2a1a0 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
2a1b0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
2a1c0 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
2a1d0 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
2a1e0 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
2a1f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
2a200 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
2a210 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
2a220 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
2a230 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
2a240 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
2a250 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
2a260 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
2a270 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
2a280 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51  ot be set..*/.SQ
2a290 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2a2a0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
2a2b0 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54  ite3 *db);.SQLIT
2a2c0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2a2d0 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
2a2e0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
2a2f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2a300 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2a310 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
2a320 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2a330 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2a340 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
2a350 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
2a360 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2a370 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
2a380 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2a390 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  : Prepared State
2a3a0 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
2a3b0 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
2a3c0 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
2a3d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a3e0 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
2a3f0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
2a400 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
2a410 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
2a420 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20 68  tement that.** h
2a430 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65 64  as been compiled
2a440 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f 72   into binary for
2a450 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20 74  m and is ready t
2a460 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e 0a  o be evaluated..
2a470 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20 65  **.** Think of e
2a480 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
2a490 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65 20  t as a separate 
2a4a0 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61 6d  computer program
2a4b0 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69 6e  .  The.** origin
2a4c0 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20 73  al SQL text is s
2a4d0 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20 70  ource code.  A p
2a4e0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a4f0 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73 20  t object .** is 
2a500 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62 6a  the compiled obj
2a510 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20 53  ect code.  All S
2a520 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  QL must be conve
2a530 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20 70  rted into a.** p
2a540 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a550 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e 20  t before it can 
2a560 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  be run..**.** Th
2a570 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66 20  e life-cycle of 
2a580 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2a590 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75 61  ment object usua
2a5a0 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74 68  lly goes like th
2a5b0 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
2a5c0 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
2a5d0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2a5e0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69 6e  ment object usin
2a5f0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
2a600 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69  re_v2()]..** <li
2a610 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f  > Bind values to
2a620 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73   [parameters] us
2a630 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
2a640 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
2a650 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
2a660 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
2a670 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2a680 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
2a690 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
2a6a0 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
2a6b0 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2a6c0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
2a6d0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65  te3_reset()] the
2a6e0 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20  n go back.**    
2a6f0 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f    to step 2.  Do
2a700 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f   this zero or mo
2a710 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
2a720 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62  > Destroy the ob
2a730 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
2a740 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e  te3_finalize()].
2a750 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70  .** </ol>.*/.typ
2a760 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
2a770 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
2a780 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
2a790 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
2a7a0 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48 4f   Limits.** METHO
2a7b0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
2a7c0 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
2a7d0 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
2a7e0 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
2a7f0 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
2a800 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
2a810 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
2a820 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
2a830 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2a840 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
2a850 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2a860 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
2a870 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
2a880 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
2a890 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2a8a0 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
2a8b0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
2a8c0 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
2a8d0 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
2a8e0 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
2a8f0 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
2a900 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2a910 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
2a920 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
2a930 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
2a940 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
2a950 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
2a960 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
2a970 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
2a980 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
2a990 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
2a9a0 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
2a9b0 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
2a9c0 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
2a9d0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
2a9e0 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
2a9f0 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
2aa00 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
2aa10 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
2aa20 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
2aa30 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
2aa40 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
2aa50 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
2aa60 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
2aa70 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
2aa80 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
2aa90 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
2aaa0 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
2aab0 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
2aac0 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
2aad0 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
2aae0 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
2aaf0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
2ab00 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
2ab10 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
2ab20 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
2ab30 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
2ab40 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2ab50 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
2ab60 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
2ab70 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
2ab80 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
2ab90 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
2aba0 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
2abb0 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
2abc0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2abd0 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
2abe0 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
2abf0 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
2ac00 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
2ac10 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
2ac20 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
2ac30 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
2ac40 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
2ac50 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
2ac60 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
2ac70 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
2ac80 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
2ac90 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
2aca0 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
2acb0 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
2acc0 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
2acd0 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
2ace0 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
2acf0 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
2ad00 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
2ad10 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
2ad20 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
2ad30 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
2ad40 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
2ad50 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
2ad60 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
2ad70 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
2ad80 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
2ad90 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
2ada0 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
2adb0 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
2adc0 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
2add0 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
2ade0 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
2adf0 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
2ae00 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
2ae10 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
2ae20 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
2ae30 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
2ae40 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
2ae50 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
2ae60 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
2ae70 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
2ae80 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
2ae90 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
2aea0 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
2aeb0 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
2aec0 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
2aed0 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
2aee0 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
2aef0 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
2af00 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
2af10 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
2af20 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
2af30 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
2af40 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
2af50 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ses..*/.SQLITE_A
2af60 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  PI int sqlite3_l
2af70 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
2af80 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
2af90 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
2afa0 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
2afb0 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
2afc0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
2afd0 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
2afe0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
2aff0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2b000 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
2b010 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
2b020 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
2b030 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
2b040 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
2b050 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
2b060 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
2b070 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
2b080 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
2b090 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
2b0a0 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
2b0b0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
2b0c0 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
2b0d0 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
2b0e0 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
2b0f0 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
2b100 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
2b110 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
2b120 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2b130 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
2b140 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
2b150 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
2b160 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
2b170 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
2b180 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2b190 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
2b1a0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
2b1b0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
2b1c0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2b1d0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
2b1e0 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
2b1f0 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
2b200 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2b210 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
2b220 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
2b230 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
2b240 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2b250 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2b260 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
2b270 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
2b280 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
2b290 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
2b2a0 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
2b2b0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
2b2c0 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
2b2d0 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
2b2e0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
2b2f0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
2b300 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2b310 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2b320 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
2b330 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2b340 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2b350 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
2b360 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
2b370 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
2b380 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
2b390 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2b3a0 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
2b3b0 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
2b3c0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
2b3d0 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
2b3e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2b3f0 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
2b400 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
2b410 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
2b420 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
2b430 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
2b440 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
2b450 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
2b460 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2b470 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2b480 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
2b490 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
2b4a0 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
2b4b0 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
2b4c0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
2b4d0 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
2b4e0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
2b4f0 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
2b500 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
2b510 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
2b520 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
2b530 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
2b540 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2b550 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2b560 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
2b570 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2b580 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
2b590 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2b5a0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2b5b0 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
2b5c0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
2b5d0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
2b5e0 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
2b5f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
2b600 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
2b610 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2b620 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
2b630 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
2b640 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
2b650 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2b660 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
2b670 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
2b680 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
2b690 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
2b6a0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2b6b0 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
2b6c0 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
2b6d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2b6e0 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
2b6f0 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
2b700 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2b710 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2b720 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
2b730 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2b740 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2b750 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
2b760 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
2b770 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
2b780 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
2b790 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
2b7a0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2b7b0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
2b7c0 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
2b7d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2b7e0 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
2b7f0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2b800 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
2b810 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
2b820 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2b830 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  [SQLITE_LIMIT_WO
2b840 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e  RKER_THREADS]] ^
2b850 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2b860 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
2b870 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2b880 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2b890 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72  of auxiliary wor
2b8a0 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74  ker threads that
2b8b0 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72   a single.** [pr
2b8c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b8d0 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64  ] may start.</dd
2b8e0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
2b8f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2b900 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
2b910 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
2b920 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b930 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
2b940 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b950 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2b960 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
2b970 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2b980 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2b990 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2b9a0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
2b9b0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
2b9c0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
2b9d0 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
2b9e0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2b9f0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2ba00 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
2ba10 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
2ba20 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2ba30 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
2ba40 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
2ba50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
2ba60 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
2ba70 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
2ba80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
2ba90 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
2baa0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
2bab0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
2bac0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
2bad0 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
2bae0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
2baf0 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
2bb00 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
2bb10 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2bb20 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20  WORKER_THREADS  
2bb30 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a 0a           11../*.
2bb40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
2bb50 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
2bb60 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
2bb70 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
2bb80 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
2bb90 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2bba0 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a  .** CONSTRUCTOR:
2bbb0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2bbc0 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
2bbd0 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
2bbe0 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
2bbf0 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
2bc00 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
2bc10 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
2bc20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
2bc30 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
2bc40 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
2bc50 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
2bc60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
2bc70 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
2bc80 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
2bc90 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2bca0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
2bcb0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
2bcc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
2bcd0 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
2bce0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2bcf0 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
2bd00 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
2bd10 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
2bd20 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
2bd30 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
2bd40 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
2bd50 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
2bd60 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
2bd70 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
2bd80 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
2bd90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2bda0 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
2bdb0 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
2bdc0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
2bdd0 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
2bde0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2bdf0 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
2be00 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
2be10 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
2be20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 7a  negative, then z
2be30 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
2be40 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
2be50 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
2be60 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f 73  ^If nByte is pos
2be70 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69  itive, then it i
2be80 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2be90 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66 72  of bytes read fr
2bea0 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e 42  om zSql.  ^If nB
2beb0 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68 65  yte is zero, the
2bec0 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a 2a  n no prepared.**
2bed0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67 65   statement is ge
2bee0 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20 74  nerated..** If t
2bef0 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 20  he caller knows 
2bf00 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69 65  that the supplie
2bf10 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d  d string is nul-
2bf20 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e  terminated, then
2bf30 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20 73  .** there is a s
2bf40 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65  mall performance
2bf50 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70 61   advantage to pa
2bf60 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
2bf70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
2bf80 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2bf90 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
2bfa0 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
2bfb0 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
2bfc0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
2bfd0 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  or..**.** ^If pz
2bfe0 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
2bff0 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
2c000 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
2c010 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
2c020 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
2c030 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
2c040 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
2c050 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
2c060 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
2c070 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
2c080 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
2c090 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
2c0a0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
2c0b0 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
2c0c0 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
2c0d0 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
2c0e0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
2c0f0 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
2c100 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c110 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
2c120 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
2c130 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
2c140 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
2c150 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
2c160 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
2c170 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
2c180 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
2c190 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
2c1a0 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
2c1b0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
2c1c0 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
2c1d0 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
2c1e0 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
2c1f0 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
2c200 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
2c210 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
2c220 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
2c230 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
2c240 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2c250 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
2c260 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
2c270 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
2c280 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
2c290 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
2c2a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
2c2b0 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
2c2c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2c2d0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
2c2e0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
2c2f0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
2c300 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
2c310 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
2c320 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
2c330 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2c340 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
2c350 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
2c360 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
2c370 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
2c380 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
2c390 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
2c3a0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
2c3b0 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
2c3c0 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
2c3d0 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
2c3e0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2c3f0 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
2c400 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
2c410 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
2c420 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
2c430 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
2c440 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
2c450 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
2c460 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
2c470 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
2c480 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
2c490 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
2c4a0 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
2c4b0 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
2c4c0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
2c4d0 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
2c4e0 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
2c4f0 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
2c500 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
2c510 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
2c520 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
2c530 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
2c540 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
2c550 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
2c560 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
2c570 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
2c580 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
2c590 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c   As many as [SQL
2c5a0 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52  ITE_MAX_SCHEMA_R
2c5b0 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73  ETRY].** retries
2c5c0 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f   will occur befo
2c5d0 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  re sqlite3_step(
2c5e0 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72  ) gives up and r
2c5f0 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e  eturns an error.
2c600 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
2c610 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
2c620 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
2c630 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2c640 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
2c650 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
2c660 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
2c670 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
2c680 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
2c690 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
2c6a0 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
2c6b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
2c6c0 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
2c6d0 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
2c6e0 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
2c6f0 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
2c700 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
2c710 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
2c720 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
2c730 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c740 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
2c750 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
2c760 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
2c770 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
2c780 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
2c790 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
2c7a0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
2c7b0 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
2c7c0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
2c7d0 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
2c7e0 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
2c7f0 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
2c800 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
2c810 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
2c820 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
2c830 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
2c840 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
2c850 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
2c860 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
2c870 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
2c880 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
2c890 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
2c8a0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2c8b0 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
2c8c0 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
2c8d0 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
2c8e0 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
2c8f0 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
2c900 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
2c910 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
2c920 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
2c930 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
2c940 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
2c950 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
2c960 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
2c970 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
2c980 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
2c990 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
2c9a0 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
2c9b0 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
2c9c0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
2c9d0 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
2c9e0 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
2c9f0 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
2ca00 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
2ca10 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
2ca20 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
2ca30 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
2ca40 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
2ca50 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d  NABLE_STAT3] com
2ca60 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2ca70 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
2ca80 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
2ca90 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2caa0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2cab0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
2cac0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
2cad0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
2cae0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2caf0 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
2cb00 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
2cb10 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
2cb20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2cb30 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2cb40 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2cb50 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2cb60 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2cb70 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2cb80 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2cb90 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
2cba0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
2cbb0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2cbc0 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2cbd0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2cbe0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2cbf0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2cc00 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2cc10 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2cc20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2cc30 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2cc40 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2cc50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2cc60 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2cc70 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2cc80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2cc90 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2cca0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2ccb0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2ccc0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2ccd0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2cce0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2ccf0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2cd00 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2cd10 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2cd20 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2cd30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2cd40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2cd50 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
2cd60 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2cd70 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2cd80 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2cd90 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2cda0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2cdb0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2cdc0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2cdd0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2cde0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2cdf0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2ce00 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2ce10 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2ce20 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2ce30 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2ce40 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2ce50 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2ce60 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2ce70 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2ce80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2ce90 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2cea0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
2ceb0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2cec0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2ced0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2cee0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2cef0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2cf00 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2cf10 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2cf20 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2cf30 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2cf40 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2cf50 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2cf60 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2cf70 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2cf80 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2cf90 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2cfa0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2cfb0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2cfc0 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2cfd0 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
2cfe0 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
2cff0 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
2d000 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2d010 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2d020 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50  he sqlite3_sql(P
2d030 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2d040 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
2d050 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55   a copy of the U
2d060 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74  TF-8.** SQL text
2d070 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20   used to create 
2d080 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d090 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a  ent] P if P was.
2d0a0 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 65 69  ** created by ei
2d0b0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
2d0c0 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2d0d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2d0e0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  6_v2()]..** ^The
2d0f0 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65   sqlite3_expande
2d100 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61  d_sql(P) interfa
2d110 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
2d120 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a  nter to a UTF-8.
2d130 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
2d140 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78  ning the SQL tex
2d150 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73 74  t of prepared st
2d160 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a  atement P with.*
2d170 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74  * [bound paramet
2d180 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a  ers] expanded..*
2d190 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
2d1a0 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72 65  le, if a prepare
2d1b0 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  d statement is c
2d1c0 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65  reated using the
2d1d0 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45   SQL.** text "SE
2d1e0 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20  LECT $abc,:xyz" 
2d1f0 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65 72  and if parameter
2d200 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74   $abc is bound t
2d210 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a  o integer 2345.*
2d220 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * and parameter 
2d230 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c  :xyz is unbound,
2d240 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71   then sqlite3_sq
2d250 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  l() will return.
2d260 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ** the original 
2d270 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20  string, "SELECT 
2d280 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73  $abc,:xyz" but s
2d290 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2d2a0 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65  sql().** will re
2d2b0 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34  turn "SELECT 234
2d2c0 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a  5,NULL".)^.**.**
2d2d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
2d2e0 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74  panded_sql() int
2d2f0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e  erface returns N
2d300 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
2d310 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73  ent memory.** is
2d320 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f   available to ho
2d330 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f  ld the result, o
2d340 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74 20  r if the result 
2d350 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68 65  would exceed the
2d360 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  .** the maximum 
2d370 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65  string length de
2d380 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
2d390 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2d3a0 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  NGTH]..**.** ^Th
2d3b0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  e [SQLITE_TRACE_
2d3c0 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70  SIZE_LIMIT] comp
2d3d0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
2d3e0 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20  limits the size 
2d3f0 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61  of.** bound para
2d400 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73  meter expansions
2d410 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
2d420 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70  OMIT_TRACE] comp
2d430 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
2d440 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74 65  on causes sqlite
2d450 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29  3_expanded_sql()
2d460 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72   to always retur
2d470 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  n NULL..**.** ^T
2d480 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e  he string return
2d490 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71  ed by sqlite3_sq
2d4a0 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20  l(P) is managed 
2d4b0 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73  by SQLite and is
2d4c0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
2d4d0 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68 65  y freed when the
2d4e0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d4f0 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2d500 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67  ..** ^The string
2d510 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2d520 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2d530 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68  l(P), on the oth
2d540 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f  er hand,.** is o
2d550 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
2d560 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
2d570 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65 65  and must be free
2d580 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74   by the applicat
2d590 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e  ion.** by passin
2d5a0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
2d5b0 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  _free()]..*/.SQL
2d5c0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2d5d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28  ar *sqlite3_sql(
2d5e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2d5f0 74 6d 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  tmt);.SQLITE_API
2d600 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
2d610 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c 69  xpanded_sql(sqli
2d620 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2d630 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d640 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2d650 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2d660 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
2d670 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  base.** METHOD: 
2d680 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2d690 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d6a0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29  stmt_readonly(X)
2d6b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2d6c0 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2d6d0 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  o) if.** and onl
2d6e0 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61 72  y if the [prepar
2d6f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20  ed statement] X 
2d700 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20  makes no direct 
2d710 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68  changes to.** th
2d720 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2d730 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a   database file..
2d740 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2d750 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2d760 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2d770 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75  ns] or.** [virtu
2d780 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74  al tables] might
2d790 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
2d7a0 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20  base indirectly 
2d7b0 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63 74  as a side effect
2d7c0 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .  .** ^(For exa
2d7d0 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c  mple, if an appl
2d7e0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20  ication defines 
2d7f0 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c  a function "eval
2d800 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c  ()" that .** cal
2d810 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ls [sqlite3_exec
2d820 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  ()], then the fo
2d830 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74  llowing SQL stat
2d840 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63  ement would.** c
2d850 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2d860 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20  se file through 
2d870 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a  side-effects:.**
2d880 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2d890 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45  <pre>.**    SELE
2d8a0 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20  CT eval('DELETE 
2d8b0 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74  FROM t1') FROM t
2d8c0 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  2;.** </pre></bl
2d8d0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
2d8e0 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65 20  But because the 
2d8f0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2d900 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  nt does not chan
2d910 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
2d920 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79  file.** directly
2d930 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  , sqlite3_stmt_r
2d940 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20  eadonly() would 
2d950 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75  still return tru
2d960 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e  e.)^.**.** ^Tran
2d970 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20  saction control 
2d980 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20  statements such 
2d990 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d  as [BEGIN], [COM
2d9a0 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d  MIT], [ROLLBACK]
2d9b0 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d  ,.** [SAVEPOINT]
2d9c0 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20  , and [RELEASE] 
2d9d0 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74  cause sqlite3_st
2d9e0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
2d9f0 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a   return true,.**
2da00 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74 65   since the state
2da10 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73  ments themselves
2da20 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79   do not actually
2da30 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61   modify the data
2da40 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68  base but.** rath
2da50 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20  er they control 
2da60 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68  the timing of wh
2da70 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65  en other stateme
2da80 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a  nts modify the .
2da90 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54  ** database.  ^T
2daa0 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20  he [ATTACH] and 
2dab0 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65  [DETACH] stateme
2dac0 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a  nts also cause.*
2dad0 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  * sqlite3_stmt_r
2dae0 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74  eadonly() to ret
2daf0 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20  urn true since, 
2db00 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74  while those stat
2db10 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65  ements.** change
2db20 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
2db30 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  on of a database
2db40 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65   connection, the
2db50 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a  y do not make .*
2db60 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  * changes to the
2db70 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2db80 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f  database files o
2db90 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  n disk..*/.SQLIT
2dba0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2dbb0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2dbc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2dbd0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2dbe0 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2dbf0 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
2dc00 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
2dc10 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  n Reset.** METHO
2dc20 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2dc30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2dc40 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
2dc50 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2dc60 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2dc70 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
2dc80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2dc90 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
2dca0 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
2dcb0 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
2dcc0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
2dcd0 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75  t has neither ru
2dce0 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  n to completion 
2dcf0 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51  (returned.** [SQ
2dd00 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20  LITE_DONE] from 
2dd10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2dd20 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72  ]) nor.** been r
2dd30 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  eset using [sqli
2dd40 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20  te3_reset(S)].  
2dd50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2dd60 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74  t_busy(S).** int
2dd70 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66  erface returns f
2dd80 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e  alse if S is a N
2dd90 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
2dda0 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20   S is not a .** 
2ddb0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
2ddc0 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65   is not a pointe
2ddd0 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72  r to a valid [pr
2dde0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ddf0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65  ].** object, the
2de00 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2de10 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2de20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72  probably undesir
2de30 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  able..**.** This
2de40 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
2de50 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e  e used in combin
2de60 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e  ation [sqlite3_n
2de70 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74  ext_stmt()].** t
2de80 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65  o locate all pre
2de90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2dea0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2deb0 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
2dec0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
2ded0 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62  are in need of b
2dee0 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69  eing reset.  Thi
2def0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a  s can be used,.*
2df00 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  * for example, i
2df10 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75  n diagnostic rou
2df20 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20  tines to search 
2df30 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a  for prepared .**
2df40 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
2df50 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74   are holding a t
2df60 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e  ransaction open.
2df70 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2df80 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2df90 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
2dfa0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2dfb0 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
2dfc0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
2dfd0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
2dfe0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
2dff0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
2e000 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e010 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
2e020 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
2e030 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e040 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
2e050 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
2e060 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
2e070 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
2e080 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
2e090 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
2e0a0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
2e0b0 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
2e0c0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
2e0d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2e0e0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
2e0f0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
2e100 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
2e110 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
2e120 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
2e130 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
2e140 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
2e150 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
2e160 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
2e170 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
2e180 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2e190 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2e1a0 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
2e1b0 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
2e1c0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
2e1d0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
2e1e0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2e1f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2e200 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
2e210 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
2e220 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
2e230 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
2e240 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
2e250 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
2e260 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2e270 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65 0a  te3_value.  The.
2e280 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
2e290 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66 61  e_dup()] interfa
2e2a0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
2e2b0 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e 65  o construct a ne
2e2c0 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64 20  w .** protected 
2e2d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66 72  sqlite3_value fr
2e2e0 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  om an unprotecte
2e2f0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2e300 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
2e310 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
2e320 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
2e330 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
2e340 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
2e350 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
2e360 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
2e370 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
2e380 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2e390 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
2e3a0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
2e3b0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
2e3c0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2e3d0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
2e3e0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
2e3f0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
2e400 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
2e410 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
2e420 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
2e430 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
2e440 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
2e450 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
2e460 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
2e470 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
2e480 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
2e490 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2e4a0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
2e4b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2e4c0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
2e4d0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
2e4e0 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2e4f0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2e500 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2e510 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2e520 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
2e530 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
2e540 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
2e550 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
2e560 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
2e570 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
2e580 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
2e590 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
2e5a0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
2e5b0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2e5c0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2e5d0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2e5e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2e5f0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
2e600 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
2e610 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
2e620 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2e630 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
2e640 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
2e650 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
2e660 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2e670 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
2e680 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2e690 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
2e6a0 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
2e6b0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2e6c0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2e6d0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2e6e0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
2e6f0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
2e700 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e710 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2e720 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2e730 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
2e740 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2e750 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
2e760 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
2e770 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2e780 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
2e790 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
2e7a0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
2e7b0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2e7c0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2e7d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2e7e0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2e7f0 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
2e800 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
2e810 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
2e820 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
2e830 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
2e840 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
2e850 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
2e860 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
2e870 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
2e880 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2e890 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
2e8a0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
2e8b0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
2e8c0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
2e8d0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
2e8e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2e8f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
2e900 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2e910 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2e920 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2e930 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
2e940 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
2e950 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
2e960 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2e970 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
2e980 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
2e990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
2e9a0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2e9b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
2e9c0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
2e9d0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2e9e0 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
2e9f0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2ea00 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
2ea10 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2ea20 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
2ea30 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2ea40 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
2ea50 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
2ea60 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
2ea70 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
2ea80 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2ea90 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2eaa0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
2eab0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
2eac0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2ead0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
2eae0 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
2eaf0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
2eb00 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
2eb10 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54   binding}.** MET
2eb20 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2eb30 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65  t.**.** ^(In the
2eb40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
2eb50 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  ext input to [sq
2eb60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2eb70 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69  ()] and its vari
2eb80 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c  ants,.** literal
2eb90 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65  s may be replace
2eba0 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65  d by a [paramete
2ebb0 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73 20  r] that matches 
2ebc0 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67  one of following
2ebd0 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a  .** templates:.*
2ebe0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2ebf0 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e  >  ?.** <li>  ?N
2ec00 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56  NN.** <li>  :VVV
2ec10 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a  .** <li>  @VVV.*
2ec20 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20  * <li>  $VVV.** 
2ec30 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74  </ul>.**.** In t
2ec40 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f  he templates abo
2ec50 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e  ve, NNN represen
2ec60 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69  ts an integer li
2ec70 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56  teral,.** and VV
2ec80 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  V represents an 
2ec90 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65  alphanumeric ide
2eca0 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65  ntifier.)^  ^The
2ecb0 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65   values of these
2ecc0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28  .** parameters (
2ecd0 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73  also called "hos
2ece0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2ecf0 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d  s" or "SQL param
2ed00 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62  eters").** can b
2ed10 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65 20  e set using the 
2ed20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2ed30 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65   routines define
2ed40 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  d here..**.** ^T
2ed50 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2ed60 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
2ed70 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2ed80 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20  es is always.** 
2ed90 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2eda0 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20   [sqlite3_stmt] 
2edb0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2edc0 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
2edd0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2ede0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a  r its variants..
2edf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
2ee00 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2ee10 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53  e index of the S
2ee20 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  QL parameter to 
2ee30 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20  be set..** ^The 
2ee40 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72  leftmost SQL par
2ee50 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2ee60 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e  dex of 1.  ^When
2ee70 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a   the same named.
2ee80 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  ** SQL parameter
2ee90 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68   is used more th
2eea0 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20  an once, second 
2eeb0 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  and subsequent.*
2eec0 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61  * occurrences ha
2eed0 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65  ve the same inde
2eee0 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20 6f  x as the first o
2eef0 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54  ccurrence..** ^T
2ef00 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d  he index for nam
2ef10 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63 61  ed parameters ca
2ef20 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75  n be looked up u
2ef30 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  sing the.** [sql
2ef40 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ef50 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49  ter_index()] API
2ef60 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54   if desired.  ^T
2ef70 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20  he index.** for 
2ef80 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72  "?NNN" parameter
2ef90 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  s is the value o
2efa0 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e  f NNN..** ^The N
2efb0 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65  NN value must be
2efc0 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74   between 1 and t
2efd0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  he [sqlite3_limi
2efe0 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  t()].** paramete
2eff0 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  r [SQLITE_LIMIT_
2f000 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
2f010 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a   (default value:
2f020 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   999)..**.** ^Th
2f030 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
2f040 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f   is the value to
2f050 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72   bind to the par
2f060 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  ameter..** ^If t
2f070 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2f080 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2f090 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  nd_text() or sql
2f0a0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2f0b0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2f0c0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2f0d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
2f0e0 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70  hen the fourth p
2f0f0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69  arameter.** is i
2f100 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65  gnored and the e
2f110 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68 65  nd result is the
2f120 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33   same as sqlite3
2f130 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a  _bind_null()..**
2f140 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72  .** ^(In those r
2f150 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76  outines that hav
2f160 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d  e a fourth argum
2f170 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69  ent, its value i
2f180 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2f190 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2f1a0 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62  parameter.  To b
2f1b0 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c  e clear: the val
2f1c0 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2f1d0 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c  ber of <u>bytes<
2f1e0 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65  /u> in the value
2f1f0 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2f200 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29   of characters.)
2f210 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75  ^.** ^If the fou
2f220 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2f230 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2f240 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  xt() or sqlite3_
2f250 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a  bind_text16().**
2f260 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2f270 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  en the length of
2f280 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
2f290 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2f2a0 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
2f2b0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
2f2c0 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65  nator..** If the
2f2d0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2f2e0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2f2f0 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61  d_blob() is nega
2f300 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  tive, then.** th
2f310 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2f320 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61  defined..** If a
2f330 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f   non-negative fo
2f340 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
2f350 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71  s provided to sq
2f360 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2f370 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
2f380 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72  bind_text16() or
2f390 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2f3a0 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74  xt64() then.** t
2f3b0 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
2f3c0 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
2f3d0 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
2f3e0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
2f3f0 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
2f400 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
2f410 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
2f420 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
2f430 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
2f440 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
2f450 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
2f460 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
2f470 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2f480 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
2f490 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
2f4a0 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
2f4b0 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
2f4c0 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
2f4d0 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
2f4e0 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
2f4f0 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
2f500 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
2f510 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2f520 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2f530 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64   to the BLOB and
2f540 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20   string binding 
2f550 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2f560 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
2f570 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
2f580 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
2f590 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
2f5a0 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
2f5b0 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
2f5c0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
2f5d0 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
2f5e0 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
2f5f0 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
2f600 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e   the call to bin
2f610 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20  d API fails..** 
2f620 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2f630 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65  gument is.** the
2f640 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b   special value [
2f650 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20  SQLITE_STATIC], 
2f660 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75  then SQLite assu
2f670 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
2f680 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69  information is i
2f690 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61  n static, unmana
2f6a0 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f  ged space and do
2f6b0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2f6c0 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  e freed..** ^If 
2f6d0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2f6e0 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65  nt has the value
2f6f0 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45   [SQLITE_TRANSIE
2f700 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  NT], then.** SQL
2f710 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77  ite makes its ow
2f720 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
2f730 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64  f the data immed
2f740 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a  iately, before.*
2f750 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  * the sqlite3_bi
2f760 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72  nd_*() routine r
2f770 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
2f780 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e  he sixth argumen
2f790 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2f7a0 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74 20  d_text64() must 
2f7b0 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51  be one of.** [SQ
2f7c0 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
2f7d0 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c  ITE_UTF16], [SQL
2f7e0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72  ITE_UTF16BE], or
2f7f0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
2f800 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20  ].** to specify 
2f810 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
2f820 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65 20  the text in the 
2f830 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
2f840 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74    If.** the sixt
2f850 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  h argument to sq
2f860 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
2f870 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f  4() is not one o
2f880 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64  f the.** allowed
2f890 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62   values shown ab
2f8a0 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74  ove, or if the t
2f8b0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ext encoding is 
2f8c0 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f  different.** fro
2f8d0 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73  m the encoding s
2f8e0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
2f8f0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c  sixth parameter,
2f900 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2f910 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  or.** is undefin
2f920 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2f930 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2f940 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
2f950 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
2f960 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
2f970 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
2f980 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
2f990 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
2f9a0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
2f9b0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
2f9c0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
2f9d0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
2f9e0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
2f9f0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
2fa00 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
2fa10 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
2fa20 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
2fa30 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
2fa40 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
2fa50 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
2fa60 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
2fa70 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
2fa80 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
2fa90 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
2faa0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
2fab0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
2fac0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
2fad0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
2fae0 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
2faf0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2fb00 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2fb10 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
2fb20 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
2fb30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2fb40 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
2fb50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fb60 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
2fb70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2fb80 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
2fb90 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
2fba0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
2fbb0 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
2fbc0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
2fbd0 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
2fbe0 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
2fbf0 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
2fc00 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
2fc10 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2fc20 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
2fc30 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
2fc40 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
2fc50 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2fc60 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
2fc70 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
2fc80 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
2fc90 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
2fca0 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
2fcb0 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
2fcc0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
2fcd0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
2fce0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
2fcf0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
2fd00 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2fd10 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
2fd20 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
2fd30 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
2fd40 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
2fd50 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54  g..** ^[SQLITE_T
2fd60 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20  OOBIG] might be 
2fd70 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20  returned if the 
2fd80 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67  size of a string
2fd90 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65   or BLOB.** exce
2fda0 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73  eds limits impos
2fdb0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
2fdc0 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
2fdd0 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a  MIT_LENGTH]) or.
2fde0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c  ** [SQLITE_MAX_L
2fdf0 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c  ENGTH]..** ^[SQL
2fe00 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
2fe10 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
2fe20 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
2fe30 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2fe40 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
2fe50 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
2fe60 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
2fe70 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2fe80 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2fe90 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2fea0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2feb0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2fec0 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
2fed0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2fee0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2fef0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ff00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2ff10 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2ff20 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2ff30 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
2ff40 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
2ff50 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2ff60 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71  3_bind_blob64(sq
2ff70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ff80 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73  , const void*, s
2ff90 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20  qlite3_uint64,. 
2ffa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ffb0 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76         void(*)(v
2ffc0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2ffd0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2ffe0 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  ind_double(sqlit
2fff0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64  e3_stmt*, int, d
30000 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41  ouble);.SQLITE_A
30010 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
30020 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
30030 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
30040 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
30050 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
30060 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
30070 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
30080 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41  int64);.SQLITE_A
30090 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
300a0 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ind_null(sqlite3
300b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  _stmt*, int);.SQ
300c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
300d0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73  ite3_bind_text(s
300e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
300f0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74  ,const char*,int
30100 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
30110 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
30120 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
30130 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
30140 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
30150 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
30160 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
30170 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
30180 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 73  e3_bind_text64(s
30190 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
301a0 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  t, const char*, 
301b0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
301c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
301d0 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29           void(*)
301e0 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65  (void*), unsigne
301f0 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67 29  d char encoding)
30200 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
30210 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
30220 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
30230 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
30240 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
30250 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
30260 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
30270 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
30280 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
30290 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
302a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
302b0 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73  blob64(sqlite3_s
302c0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
302d0 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a  e3_uint64);../*.
302e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
302f0 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
30300 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eters.** METHOD:
30310 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30320 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
30330 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
30340 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
30350 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
30360 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
30370 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30380 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
30390 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
303a0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
303b0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
303c0 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
303d0 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
303e0 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
303f0 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
30400 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
30410 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
30420 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
30430 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
30440 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
30450 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
30460 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
30470 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
30480 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
30490 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
304a0 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
304b0 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
304c0 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
304d0 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
304e0 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
304f0 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
30500 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
30510 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
30520 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
30530 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
30540 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
30550 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
30560 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
30570 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
30580 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30590 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
305a0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
305b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
305c0 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
305d0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
305e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
305f0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
30600 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
30610 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
30620 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
30630 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
30640 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
30650 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
30660 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
30670 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
30680 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
30690 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
306a0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
306b0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
306c0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
306d0 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
306e0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
306f0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
30700 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
30710 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
30720 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
30730 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
30740 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
30750 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
30760 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
30770 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
30780 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
30790 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
307a0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
307b0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
307c0 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
307d0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
307e0 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
307f0 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
30800 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
30810 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
30820 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
30830 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
30840 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
30850 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
30860 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  t host parameter
30870 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
30880 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a   1, not 0..**.**
30890 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e   ^If the value N
308a0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
308b0 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20   or if the N-th 
308c0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
308d0 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e  nameless, then N
308e0 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ULL is returned.
308f0 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
30900 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77  string is.** alw
30910 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63  ays in UTF-8 enc
30920 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  oding even if th
30930 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  e named paramete
30940 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61  r was.** origina
30950 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73  lly specified as
30960 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69   UTF-16 in [sqli
30970 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
30980 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
30990 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
309a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
309b0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
309c0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
309d0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
309e0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
309f0 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
30a00 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
30a10 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
30a20 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
30a30 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
30a40 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
30a50 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ter_name(sqlite3
30a60 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f  _stmt*, int);../
30a70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
30a80 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65  ndex Of A Parame
30a90 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e  ter With A Given
30aa0 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Name.** METHOD:
30ab0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
30ac0 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
30ad0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
30ae0 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
30af0 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
30b00 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
30b10 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
30b20 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
30b30 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
30b40 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
30b50 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
30b60 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
30b70 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
30b80 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
30b90 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
30ba0 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
30bb0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
30bc0 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
30bd0 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
30be0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
30bf0 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
30c00 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
30c10 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
30c20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30c30 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
30c40 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
30c50 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
30c60 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
30c70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
30c80 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
30c90 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
30ca0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30cb0 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  name()]..*/.SQLI
30cc0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
30cd0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
30ce0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
30cf0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
30d00 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
30d10 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
30d20 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
30d30 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
30d40 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44  tement.** METHOD
30d50 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
30d60 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
30d70 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
30d80 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
30d90 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
30da0 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
30db0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
30dc0 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
30dd0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
30de0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
30df0 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
30e00 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
30e10 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
30e20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  NULL..*/.SQLITE_
30e30 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
30e40 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
30e50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
30e60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30e70 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
30e80 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
30e90 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
30ea0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
30eb0 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
30ec0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
30ed0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
30ee0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
30ef0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
30f00 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
30f10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
30f20 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
30f30 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
30f40 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
30f50 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
30f60 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
30f70 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  TE])..**.** See 
30f80 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
30f90 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
30fa0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
30fb0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
30fc0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
30fd0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
30fe0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
30ff0 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
31000 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult Set.** METHO
31010 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
31020 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
31030 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
31040 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
31050 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
31060 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
31070 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
31080 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
31090 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
310a0 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
310b0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
310c0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
310d0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
310e0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
310f0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
31100 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
31110 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
31120 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
31130 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
31140 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
31150 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
31160 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
31170 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
31180 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
31190 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
311a0 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
311b0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
311c0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
311d0 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
311e0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
311f0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
31200 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
31210 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
31220 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
31230 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
31240 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
31250 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
31260 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
31270 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
31280 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
31290 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
312a0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
312b0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
312c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
312d0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
312e0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
312f0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
31300 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
31310 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
31320 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
31330 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
31340 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
31350 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
31360 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
31370 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
31380 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
31390 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
313a0 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
313b0 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
313c0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
313d0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
313e0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
313f0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
31400 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
31410 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
31420 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
31430 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
31440 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
31450 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
31460 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
31470 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
31480 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
31490 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
314a0 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
314b0 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
314c0 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
314d0 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
314e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
314f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
31500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
31510 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31520 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt N);.SQLITE_AP
31530 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
31540 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
31550 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
31560 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
31570 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
31580 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
31590 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20  Query Result.** 
315a0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
315b0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  stmt.**.** ^Thes
315c0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
315d0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
315e0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
315f0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
31600 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
31610 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
31620 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
31630 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
31640 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
31650 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
31660 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
31670 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
31680 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
31690 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
316a0 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
316b0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
316c0 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
316d0 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
316e0 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
316f0 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
31700 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
31710 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
31720 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
31730 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
31740 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
31750 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
31760 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
31770 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
31780 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
31790 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
317a0 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
317b0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
317c0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
317d0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
317e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
317f0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
31800 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
31810 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
31820 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
31830 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
31840 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
31850 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
31860 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
31870 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
31880 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
31890 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
318a0 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
318b0 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
318c0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
318d0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
318e0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
318f0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
31900 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
31910 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
31920 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31930 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
31940 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
31950 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
31960 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
31970 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
31980 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
31990 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
319a0 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
319b0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
319c0 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
319d0 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
319e0 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
319f0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
31a00 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
31a10 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
31a20 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
31a30 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
31a40 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
31a50 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
31a60 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
31a70 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
31a80 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
31a90 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
31aa0 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
31ab0 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
31ac0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
31ad0 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
31ae0 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
31af0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
31b00 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
31b10 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
31b20 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
31b30 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
31b40 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
31b50 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
31b60 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
31b70 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
31b80 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
31b90 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
31ba0 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
31bb0 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
31bc0 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
31bd0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
31be0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
31bf0 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
31c00 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
31c10 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
31c20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
31c30 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
31c40 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
31c50 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
31c60 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
31c70 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
31c80 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
31c90 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
31ca0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
31cb0 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
31cc0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31cd0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
31ce0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
31cf0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
31d00 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
31d10 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
31d20 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
31d30 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
31d40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
31d50 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
31d60 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
31d70 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
31d80 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
31d90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31da0 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
31db0 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
31dc0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
31dd0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
31de0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c  ndefined..*/.SQL
31df0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
31e00 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
31e10 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
31e20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
31e30 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
31e40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
31e50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
31e60 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
31e70 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
31e80 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
31e90 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
31ea0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
31eb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
31ec0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
31ed0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
31ee0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
31ef0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
31f00 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
31f10 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
31f20 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
31f30 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
31f40 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
31f50 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
31f60 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31f70 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
31f80 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
31f90 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
31fa0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
31fb0 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
31fc0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
31fd0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
31fe0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  _stmt.**.** ^(Th
31ff0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
32000 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
32010 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
32020 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
32030 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
32040 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
32050 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
32060 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
32070 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
32080 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
32090 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
320a0 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
320b0 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
320c0 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
320d0 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
320e0 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
320f0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
32100 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
32110 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
32120 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
32130 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
32140 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
32150 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
32160 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
32170 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
32180 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
32190 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
321a0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
321b0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
321c0 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
321d0 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
321e0 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
321f0 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
32200 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
32210 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
32220 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
32230 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
32240 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
32250 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
32260 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
32270 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
32280 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
32290 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
322a0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
322b0 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
322c0 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
322d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
322e0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
322f0 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
32300 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
32310 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
32320 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
32330 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
32340 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
32350 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
32360 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
32370 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
32380 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
32390 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
323a0 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
323b0 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
323c0 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
323d0 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
323e0 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
323f0 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
32400 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
32410 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
32420 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
32430 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
32440 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
32450 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
32460 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
32470 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
32480 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
32490 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
324a0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
324b0 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
324c0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
324d0 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
324e0 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
324f0 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
32500 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
32510 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
32520 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
32530 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
32540 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
32550 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
32560 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
32570 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
32580 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
32590 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
325a0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
325b0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
325c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
325d0 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
325e0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
325f0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
32600 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
32610 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
32620 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
32630 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
32640 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
32650 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
32660 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
32670 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
32680 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
32690 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
326a0 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
326b0 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
326c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
326d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
326e0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
326f0 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
32700 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
32710 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
32720 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
32730 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
32740 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
32750 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
32760 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
32770 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
32780 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
32790 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
327a0 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
327b0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
327c0 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
327d0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
327e0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
327f0 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
32800 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
32810 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
32820 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
32830 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
32840 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
32850 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
32860 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
32870 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
32880 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
32890 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
328a0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
328b0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
328c0 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
328d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
328e0 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
328f0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
32900 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
32910 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
32920 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
32930 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
32940 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
32950 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
32960 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
32970 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
32980 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
32990 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
329a0 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
329b0 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
329c0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
329d0 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
329e0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
329f0 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
32a00 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
32a10 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
32a20 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
32a30 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
32a40 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
32a50 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
32a60 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
32a70 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
32a80 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
32a90 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
32aa0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
32ab0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
32ac0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
32ad0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
32ae0 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
32af0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
32b00 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
32b10 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
32b20 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
32b30 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
32b40 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
32b50 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
32b60 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
32b70 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
32b80 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
32b90 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
32ba0 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
32bb0 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
32bc0 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
32bd0 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
32be0 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
32bf0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
32c00 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
32c10 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
32c20 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
32c30 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
32c40 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
32c50 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
32c60 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
32c70 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
32c80 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
32c90 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
32ca0 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
32cb0 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
32cc0 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
32cd0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
32ce0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
32cf0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
32d00 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
32d10 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
32d20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
32d30 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
32d40 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
32d50 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
32d60 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
32d70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
32d80 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
32d90 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
32da0 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
32db0 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
32dc0 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
32dd0 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
32de0 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
32df0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
32e00 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
32e10 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
32e20 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
32e30 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
32e40 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
32e50 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
32e60 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
32e70 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
32e80 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
32e90 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
32ea0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
32eb0 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
32ec0 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
32ed0 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
32ee0 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
32ef0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
32f00 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
32f10 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
32f20 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
32f30 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
32f40 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
32f50 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
32f60 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
32f70 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
32f80 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
32f90 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
32fa0 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
32fb0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
32fc0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
32fd0 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
32fe0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
32ff0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
33000 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
33010 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
33020 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
33030 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
33040 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
33050 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
33060 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
33070 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
33080 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
33090 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
330a0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
330b0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
330c0 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
330d0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
330e0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
330f0 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
33100 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
33110 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
33120 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
33130 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
33140 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
33150 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
33160 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
33170 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
33180 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
33190 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
331a0 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
331b0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
331c0 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
331d0 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
331e0 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
331f0 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
33200 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
33210 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
33220 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
33230 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
33240 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
33250 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
33260 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
33270 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
33280 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
33290 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
332a0 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
332b0 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
332c0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
332d0 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
332e0 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
332f0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
33300 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
33310 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
33320 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
33330 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
33340 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
33350 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
33360 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
33370 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
33380 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
33390 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
333a0 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
333b0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
333c0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
333d0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
333e0 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
333f0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
33400 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
33410 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
33420 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
33430 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
33440 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
33450 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
33460 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
33470 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
33480 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
33490 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
334a0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
334b0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
334c0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
334d0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
334e0 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
334f0 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
33500 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
33510 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
33520 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
33530 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
33540 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
33550 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
33560 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
33570 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
33580 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
33590 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
335a0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
335b0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
335c0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
335d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
335e0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
335f0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
33600 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
33610 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
33620 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
33630 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
33640 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
33650 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
33660 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
33670 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
33680 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
33690 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
336a0 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
336b0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
336c0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
336d0 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
336e0 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
336f0 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
33700 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33710 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
33720 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
33730 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
33740 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
33750 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
33760 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
33770 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
33780 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33790 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
337a0 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
337b0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
337c0 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
337d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
337e0 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
337f0 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
33800 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
33810 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68   pointer..** ^Th
33820 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
33830 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
33840 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65  returns 0 if the
33850 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
33860 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
33870 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20  ep](P) returned 
33880 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
33890 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
338a0 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69  a_count(P).** wi
338b0 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65  ll return non-ze
338c0 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63  ro if previous c
338d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
338e0 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
338f0 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57  d.** [SQLITE_ROW
33900 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65  ], except in the
33910 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52   case of the [PR
33920 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c  AGMA incremental
33930 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72  _vacuum].** wher
33940 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  e it always retu
33950 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65  rns zero since e
33960 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74  ach step of that
33970 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70   multi-step.** p
33980 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20  ragma returns 0 
33990 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e  columns of data.
339a0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
339b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
339c0 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c  _count()].*/.SQL
339d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
339e0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
339f0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
33a00 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
33a10 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
33a20 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
33a30 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
33a40 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
33a50 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
33a60 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
33a70 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
33a80 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
33a90 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
33aa0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
33ab0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
33ac0 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
33ad0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
33ae0 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
33af0 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
33b00 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
33b10 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
33b20 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
33b30 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
33b40 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
33b50 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
33b60 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
33b70 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
33b80 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
33b90 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
33ba0 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
33bb0 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
33bc0 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
33bd0 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
33be0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
33bf0 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
33c00 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
33c10 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
33c20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
33c30 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
33c40 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
33c50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33c60 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
33c70 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
33c80 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
33c90 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
33ca0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
33cb0 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
33cc0 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
33cd0 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
33ce0 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
33cf0 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
33d00 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
33d10 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
33d20 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
33d30 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
33d40 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
33d50 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
33d60 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
33d70 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  tmt.**.** ^These
33d80 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
33d90 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
33da0 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
33db0 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
33dc0 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
33dd0 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
33de0 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
33df0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
33e00 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
33e10 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
33e20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
33e30 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
33e40 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
33e50 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
33e60 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
33e70 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
33e80 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
33e90 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
33ea0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
33eb0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
33ec0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
33ed0 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
33ee0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
33ef0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
33f00 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
33f10 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
33f20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
33f30 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
33f40 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
33f50 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
33f60 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
33f70 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
33f80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
33f90 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
33fa0 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
33fb0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
33fc0 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
33fd0 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
33fe0 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
33ff0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
34000 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
34010 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
34020 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
34030 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
34040 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
34050 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
34060 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
34070 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
34080 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
34090 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
340a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
340b0 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
340c0 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
340d0 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
340e0 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
340f0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
34100 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
34110 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
34120 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
34130 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34140 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
34150 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
34160 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
34170 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
34180 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
34190 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
341a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
341b0 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
341c0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
341d0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
341e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
341f0 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
34200 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
34210 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
34220 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
34230 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
34240 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
34250 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
34260 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
34270 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
34280 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
34290 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
342a0 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
342b0 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
342c0 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
342d0 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
342e0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
342f0 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
34300 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
34310 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
34320 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
34330 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
34340 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
34350 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
34360 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
34370 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
34380 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
34390 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
343a0 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
343b0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
343c0 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
343d0 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
343e0 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
343f0 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
34400 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
34410 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
34420 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
34430 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
34440 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
34450 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
34460 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
34470 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34480 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
34490 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
344a0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
344b0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
344c0 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
344d0 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
344e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
344f0 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
34500 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
34510 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
34520 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
34530 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
34540 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
34550 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
34560 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34570 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
34580 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
34590 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
345a0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
345b0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
345c0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
345d0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
345e0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
345f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
34600 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
34610 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
34620 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
34630 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
34640 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
34650 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
34660 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
34670 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
34680 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
34690 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
346a0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
346b0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
346c0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
346d0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
346e0 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
346f0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
34700 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
34710 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
34720 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
34730 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
34740 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
34750 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
34760 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
34770 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
34780 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
34790 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
347a0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
347b0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
347c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
347d0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
347e0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
347f0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
34800 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
34810 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
34820 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
34830 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
34840 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
34850 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
34860 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
34870 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
34880 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
34890 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
348a0 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
348b0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
348c0 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
348d0 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
348e0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
348f0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
34900 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
34910 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
34920 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
34930 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
34940 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
34950 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
34960 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
34970 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
34980 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
34990 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
349a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
349b0 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
349c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
349d0 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
349e0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
349f0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
34a00 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
34a10 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
34a20 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
34a30 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
34a40 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
34a50 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
34a60 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
34a70 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
34a80 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
34a90 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
34aa0 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
34ab0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
34ac0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
34ad0 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
34ae0 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
34af0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c  pointer..**.** <
34b00 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e  b>Warning:</b> ^
34b10 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
34b20 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
34b30 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
34b40 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
34b50 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
34b60 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e  lue] object.  In
34b70 20 61 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64   a multithreaded
34b80 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a   environment,.**
34b90 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
34ba0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
34bb0 6a 65 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ject may only be
34bc0 20 75 73 65 64 20 73 61 66 65 6c 79 20 77 69 74   used safely wit
34bd0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  h.** [sqlite3_bi
34be0 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  nd_value()] and 
34bf0 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
34c00 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20  value()]..** If 
34c10 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  the [unprotected
34c20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
34c30 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
34c40 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
34c50 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
34c60 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74  s used in any ot
34c70 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69  her way, includi
34c80 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72  ng calls.** to r
34c90 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71  outines like [sq
34ca0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
34cb0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
34cc0 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
34cd0 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
34ce0 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62  _bytes()], the b
34cf0 65 68 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74  ehavior is not t
34d00 68 72 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a  hreadsafe..**.**
34d10 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
34d20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65  attempt to conve
34d30 72 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65  rt the value whe
34d40 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20  re appropriate. 
34d50 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65   ^For.** example
34d60 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61  , if the interna
34d70 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
34d80 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20   is FLOAT and a 
34d90 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69  text result.** i
34da0 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71  s requested, [sq
34db0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
34dc0 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  ] is used intern
34dd0 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20  ally to perform 
34de0 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  the.** conversio
34df0 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  n automatically.
34e00 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e    ^(The followin
34e10 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20  g table details 
34e20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a  the conversions.
34e30 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c  ** that are appl
34e40 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ied:.**.** <bloc
34e50 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c  kquote>.** <tabl
34e60 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a  e border="1">.**
34e70 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e   <tr><th> Intern
34e80 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  al<br>Type <th> 
34e90 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70  Requested<br>Typ
34ea0 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69  e <th>  Conversi
34eb0 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64  on.**.** <tr><td
34ec0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
34ed0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52  INTEGER   <td> R
34ee0 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74  esult is 0.** <t
34ef0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
34f00 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
34f10 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e  td> Result is 0.
34f20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
34f30 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45  ULL    <td>   TE
34f40 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  XT    <td> Resul
34f50 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
34f60 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
34f70 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
34f80 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
34f90 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ult is a NULL po
34fa0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
34fb0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
34fc0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
34fd0 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
34fe0 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
34ff0 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
35000 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
35010 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
35020 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
35030 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
35040 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
35050 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
35060 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
35070 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
35080 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
35090 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41  TEGER   <td> [CA
350a0 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a  ST] to INTEGER.*
350b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
350c0 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
350d0 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
350e0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
350f0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
35100 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
35110 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43   BLOB    <td> [C
35120 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20  AST] to BLOB.** 
35130 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
35140 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
35150 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
35160 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
35170 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
35180 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
35190 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a   [CAST] to REAL.
351a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
351b0 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  T    <td>   BLOB
351c0 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e      <td> No chan
351d0 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ge.** <tr><td>  
351e0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54  BLOB    <td> INT
351f0 45 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53  EGER   <td> [CAS
35200 54 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a  T] to INTEGER.**
35210 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
35220 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
35230 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
35240 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64   REAL.** <tr><td
35250 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
35260 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
35270 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
35280 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
35290 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
352a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
352b0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
352c0 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
352d0 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
352e0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
352f0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
35300 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
35310 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
35320 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
35330 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
35340 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
35350 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
35360 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
35370 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
35380 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
35390 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
353a0 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
353b0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
353c0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
353d0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
353e0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
353f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35400 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
35410 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35420 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
35430 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
35440 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
35450 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
35460 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
35470 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
35480 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
35490 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
354a0 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
354b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
354c0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
354d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
354e0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
354f0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
35500 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
35510 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
35520 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
35530 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
35540 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
35550 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
35560 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
35570 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
35580 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
35590 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
355a0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
355b0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
355c0 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
355d0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
355e0 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
355f0 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
35600 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
35610 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
35620 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
35630 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
35640 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
35650 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
35660 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
35670 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
35680 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
35690 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
356a0 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
356b0 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
356c0 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
356d0 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
356e0 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
356f0 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
35700 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
35710 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
35720 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
35730 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
35740 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
35750 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
35760 65 73 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  est policy is to
35770 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
35780 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
35790 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
357a0 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
357b0 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
357c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
357d0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
357e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
357f0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
35800 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
35810 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
35820 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
35830 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
35840 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
35850 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
35860 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
35870 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
35880 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
35890 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
358a0 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
358b0 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
358c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
358d0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
358e0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
358f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
35900 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
35910 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
35920 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
35930 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
35940 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
35950 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
35960 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
35970 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
35980 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
35990 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
359a0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
359b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
359c0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
359d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
359e0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
359f0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
35a00 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
35a10 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
35a20 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
35a30 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
35a40 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
35a50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35a60 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
35a70 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
35a80 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
35a90 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
35aa0 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
35ab0 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
35ac0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
35ad0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
35ae0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
35af0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
35b00 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
35b10 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
35b20 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
35b30 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
35b40 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
35b50 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
35b60 61 6c 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f  ally.  Do <em>no
35b70 74 3c 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20  t</em> pass the 
35b80 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
35b90 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
35ba0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
35bb0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
35bc0 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
35bd0 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
35be0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
35bf0 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
35c00 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
35c10 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
35c20 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
35c30 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
35c40 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
35c50 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
35c60 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
35c70 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
35c80 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
35c90 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
35ca0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
35cb0 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
35cc0 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
35cd0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
35ce0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
35cf0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
35d00 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
35d10 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ].)^.*/.SQLITE_A
35d20 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
35d30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
35d40 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
35d50 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
35d60 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
35d70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35d80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
35d90 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
35da0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
35db0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
35dc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
35dd0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
35de0 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c  E_API double sql
35df0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
35e00 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
35e10 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
35e20 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
35e30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
35e40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
35e50 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
35e60 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
35e70 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
35e80 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
35e90 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
35ea0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
35eb0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
35ec0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
35ed0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
35ee0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
35ef0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
35f00 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
35f10 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
35f20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
35f30 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
35f40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
35f50 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
35f60 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
35f70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
35f80 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
35f90 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
35fa0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
35fb0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
35fc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
35fd0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
35fe0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
35ff0 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20  .** DESTRUCTOR: 
36000 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
36010 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36020 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
36030 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
36040 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
36050 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
36060 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
36070 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
36080 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
36090 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e  nt encountered n
360a0 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69  o errors.** or i
360b0 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
360c0 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76  is never been ev
360d0 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71  aluated, then sq
360e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
360f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49   returns.** SQLI
36100 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20  TE_OK.  ^If the 
36110 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
36120 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d  uation of statem
36130 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68  ent S failed, th
36140 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69  en.** sqlite3_fi
36150 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e  nalize(S) return
36160 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74  s the appropriat
36170 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f  e [error code] o
36180 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65  r.** [extended e
36190 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
361a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
361b0 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69  inalize(S) routi
361c0 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64  ne can be called
361d0 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75   at any point du
361e0 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65  ring.** the life
361f0 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61   cycle of [prepa
36200 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
36210 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74  :.** before stat
36220 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20  ement S is ever 
36230 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72  evaluated, after
36240 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  .** one or more 
36250 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
36260 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61  3_reset()], or a
36270 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a  fter any call.**
36280 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
36290 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20  p()] regardless 
362a0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
362b0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
362c0 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64  has.** completed
362d0 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a   execution..**.*
362e0 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69  * ^Invoking sqli
362f0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f  te3_finalize() o
36300 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
36310 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e   is a harmless n
36320 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  o-op..**.** The 
36330 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
36340 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20   finalize every 
36350 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36360 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  ent] in order to
36370 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72   avoid.** resour
36380 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73  ce leaks.  It is
36390 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f   a grievous erro
363a0 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63  r for the applic
363b0 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20  ation to try to 
363c0 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65  use.** a prepare
363d0 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  d statement afte
363e0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
363f0 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73  nalized.  Any us
36400 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a  e of a prepared.
36410 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ** statement aft
36420 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
36430 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73  inalized can res
36440 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
36450 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61   and.** undesira
36460 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63  ble behavior suc
36470 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61  h as segfaults a
36480 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69  nd heap corrupti
36490 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  on..*/.SQLITE_AP
364a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  I int sqlite3_fi
364b0 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
364c0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
364d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
364e0 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
364f0 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
36500 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
36510 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 68  e3_stmt.**.** Th
36520 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
36530 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
36540 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
36550 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
36560 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
36570 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
36580 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
36590 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
365a0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
365b0 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
365c0 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
365d0 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
365e0 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
365f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
36600 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
36610 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
36620 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
36630 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
36640 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
36650 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
36660 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
36670 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
36680 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
36690 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
366a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
366b0 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
366c0 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
366d0 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
366e0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
366f0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
36700 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
36710 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
36720 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
36730 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
36740 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
36750 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
36760 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
36770 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
36780 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
36790 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
367a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
367b0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
367c0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
367d0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
367e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
367f0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
36800 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
36810 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
36820 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
36830 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
36840 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
36850 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
36860 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
36870 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
36880 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
36890 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
368a0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
368b0 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
368c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
368d0 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
368e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
368f0 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49  ment] S..*/.SQLI
36900 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
36910 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
36920 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
36930 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36940 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
36950 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
36960 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
36970 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
36980 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
36990 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
369a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
369b0 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
369c0 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
369d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
369e0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d   functions}.** M
369f0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
36a00 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
36a10 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76  tions (collectiv
36a20 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75  ely known as "fu
36a30 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
36a40 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72  routines").** ar
36a50 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51  e used to add SQ
36a60 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
36a70 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20  ggregates or to 
36a80 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68  redefine the beh
36a90 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73  avior.** of exis
36aa0 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f  ting SQL functio
36ab0 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
36ac0 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66  .  The only diff
36ad0 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a  erences between.
36ae0 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  ** these routine
36af0 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65  s are the text e
36b00 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64  ncoding expected
36b10 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f   for.** the seco
36b20 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  nd parameter (th
36b30 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75  e name of the fu
36b40 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65  nction being cre
36b50 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ated).** and the
36b60 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73   presence or abs
36b70 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75  ence of a destru
36b80 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f  ctor callback fo
36b90 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  r.** the applica
36ba0 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
36bb0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
36bc0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
36bd0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
36be0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68  onnection] to wh
36bf0 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66  ich the SQL.** f
36c00 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  unction is to be
36c10 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20   added.  ^If an 
36c20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73  application uses
36c30 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64   more than one d
36c40 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
36c50 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69  ction then appli
36c60 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
36c70 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73  QL functions mus
36c80 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f  t be added.** to
36c90 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
36ca0 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61  onnection separa
36cb0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tely..**.** ^The
36cc0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
36cd0 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  r is the name of
36ce0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
36cf0 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20  n to be created 
36d00 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e  or.** redefined.
36d10 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66    ^The length of
36d20 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d   the name is lim
36d30 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65  ited to 255 byte
36d40 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20  s in a UTF-8.** 
36d50 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20  representation, 
36d60 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65  exclusive of the
36d70 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72   zero-terminator
36d80 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  .  ^Note that th
36d90 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68  e name.** length
36da0 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46   limit is in UTF
36db0 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68  -8 bytes, not ch
36dc0 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46  aracters nor UTF
36dd0 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20  -16 bytes.  .** 
36de0 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20  ^Any attempt to 
36df0 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f  create a functio
36e00 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20  n with a longer 
36e10 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73  name.** will res
36e20 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d  ult in [SQLITE_M
36e30 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74  ISUSE] being ret
36e40 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
36e50 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
36e60 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74  r (nArg).** is t
36e70 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  he number of arg
36e80 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20  uments that the 
36e90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
36ea0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b  ** aggregate tak
36eb0 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72  es. ^If this par
36ec0 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68  ameter is -1, th
36ed0 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  en the SQL funct
36ee0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
36ef0 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79  ate may take any
36f00 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
36f10 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61  ents between 0 a
36f20 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20  nd the limit.** 
36f30 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  set by [sqlite3_
36f40 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
36f50 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
36f60 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69  G]).  If the thi
36f70 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  rd.** parameter 
36f80 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20  is less than -1 
36f90 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
36fa0 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68  127 then the beh
36fb0 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65  avior is.** unde
36fc0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
36fd0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
36fe0 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70  er, eTextRep, sp
36ff0 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20  ecifies what.** 
37000 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74  [SQLITE_UTF8 | t
37010 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68  ext encoding] th
37020 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  is SQL function 
37030 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69  prefers for.** i
37040 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ts parameters.  
37050 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
37060 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73 20  should set this 
37070 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
37080 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
37090 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   if the function
370a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
370b0 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c  invokes .** [sql
370c0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
370d0 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70  6le()] on an inp
370e0 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ut, or [SQLITE_U
370f0 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a 2a  TF16BE] if the.*
37100 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
37110 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65   invokes [sqlite
37120 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
37130 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
37140 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   or.** [SQLITE_U
37150 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74 65  TF16] if [sqlite
37160 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
37170 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b 53  ] is used, or [S
37180 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f  QLITE_UTF8].** o
37190 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65 20  therwise.  ^The 
371a0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
371b0 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
371c0 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  red multiple tim
371d0 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66  es using.** diff
371e0 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64 20  erent preferred 
371f0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20  text encodings, 
37200 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 69  with different i
37210 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
37220 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64  or.** each encod
37230 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75  ing..** ^When mu
37240 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
37250 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
37260 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20  me function are 
37270 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74  available, SQLit
37280 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74  e.** will pick t
37290 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f  he one that invo
372a0 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  lves the least a
372b0 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f  mount of data co
372c0 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
372d0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
372e0 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e  meter may option
372f0 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69 74  ally be ORed wit
37300 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d  h [SQLITE_DETERM
37310 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73  INISTIC].** to s
37320 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20 66  ignal that the f
37330 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77  unction will alw
37340 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
37350 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65 6e  ame result given
37360 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e 70  .** the same inp
37370 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69 6e  uts within a sin
37380 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
37390 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e  t.  Most SQL fun
373a0 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65  ctions are.** de
373b0 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
373c0 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64  e built-in [rand
373d0 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74 69  om()] SQL functi
373e0 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  on is an example
373f0 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   of a.** functio
37400 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64 65  n that is not de
37410 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54 68  terministic.  Th
37420 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20 70  e SQLite query p
37430 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20 74  lanner is able t
37440 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64 64  o.** perform add
37450 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61  itional optimiza
37460 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69  tions on determi
37470 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73  nistic functions
37480 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74  , so use.** of t
37490 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  he [SQLITE_DETER
374a0 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20 69  MINISTIC] flag i
374b0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68  s recommended wh
374c0 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a  ere possible..**
374d0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
374e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
374f0 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
37500 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
37510 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
37520 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
37530 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
37540 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
37550 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
37560 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
37570 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
37580 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
37590 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
375a0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
375b0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
375c0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
375d0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
375e0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
375f0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
37600 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
37610 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
37620 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
37630 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
37640 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
37650 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
37660 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
37670 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
37680 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
37690 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
376a0 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
376b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
376c0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
376d0 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
376e0 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
376f0 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
37700 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
37710 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
37720 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
37730 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
37740 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
37750 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
37760 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
37770 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
37780 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
37790 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
377a0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
377b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
377c0 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
377d0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
377e0 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
377f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
37800 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
37810 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
37820 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
37830 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
37840 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
37850 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
37860 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
37870 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
37880 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
37890 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
378a0 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
378b0 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
378c0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
378d0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
378e0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
378f0 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
37900 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
37910 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
37920 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
37930 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
37940 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
37950 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
37960 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
37970 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
37980 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
37990 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
379a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
379b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
379c0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
379d0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
379e0 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
379f0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
37a00 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
37a10 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
37a20 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
37a30 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
37a40 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
37a50 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
37a60 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
37a70 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
37a80 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
37a90 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
37aa0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
37ab0 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
37ac0 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
37ad0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
37ae0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
37af0 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
37b00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37b10 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
37b20 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
37b30 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
37b40 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
37b50 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
37b60 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
37b70 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
37b80 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
37b90 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
37ba0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
37bb0 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
37bc0 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
37bd0 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
37be0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
37bf0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
37c00 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
37c10 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
37c20 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
37c30 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
37c40 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
37c50 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
37c60 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
37c70 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
37c80 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
37c90 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
37ca0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
37cb0 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
37cc0 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
37cd0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
37ce0 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
37cf0 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
37d00 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
37d10 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
37d20 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
37d30 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
37d40 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
37d50 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
37d60 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
37d70 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
37d80 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
37d90 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
37da0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
37db0 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
37dc0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
37dd0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
37de0 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
37df0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
37e00 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
37e10 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
37e20 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
37e30 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
37e40 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
37e50 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
37e60 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
37e70 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
37e80 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
37e90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37ea0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
37eb0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
37ec0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
37ed0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
37ee0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
37ef0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
37f00 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37f10 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
37f20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
37f30 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
37f40 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
37f50 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
37f60 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
37f70 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
37f80 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
37f90 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
37fa0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
37fb0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
37fc0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
37fd0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
37fe0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
37ff0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
38000 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
38010 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
38020 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  ext*).);.SQLITE_
38030 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
38040 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
38050 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
38060 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
38070 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
38080 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
38090 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
380a0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
380b0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
380c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
380d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
380e0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
380f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38100 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
38110 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
38120 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
38130 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f  _context*),.  vo
38140 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
38150 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
38160 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
38170 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
38180 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
38190 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
381a0 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
381b0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
381c0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
381d0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
381e0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
381f0 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
38200 20 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50       1    /* IMP
38210 3a 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20  : R-37514-35566 
38220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
38230 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
38240 20 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d   2    /* IMP: R-
38250 30 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23  03371-37637 */.#
38260 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
38270 46 31 36 42 45 20 20 20 20 20 20 20 20 33 20 20  F16BE        3  
38280 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37    /* IMP: R-5197
38290 31 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69  1-34154 */.#defi
382a0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20  ne SQLITE_UTF16 
382b0 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a           4    /*
382c0 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65   Use native byte
382d0 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e   order */.#defin
382e0 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20  e SQLITE_ANY    
382f0 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20          5    /* 
38300 44 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64  Deprecated */.#d
38310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
38320 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
38330 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
38340 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
38350 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
38360 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46  3REF: Function F
38370 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lags.**.** These
38380 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62   constants may b
38390 65 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20  e ORed together 
383a0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
383b0 4c 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66  LITE_UTF8 | pref
383c0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
383d0 69 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72  ing] as the four
383e0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  th argument.** t
383f0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
38400 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b  e_function()], [
38410 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
38420 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72  unction16()], or
38430 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
38440 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
38450 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  )]..*/.#define S
38460 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53  QLITE_DETERMINIS
38470 54 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a  TIC    0x800../*
38480 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
38490 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
384a0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
384b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
384c0 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
384d0 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
384e0 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
384f0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
38500 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
38510 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
38520 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
38530 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
38540 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
38550 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
38560 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
38570 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
38580 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
38590 20 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72   To encourage pr
385a0 6f 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f  ogrammers to avo
385b0 69 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63  id.** these func
385c0 74 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e  tions, we will n
385d0 6f 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20  ot explain what 
385e0 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e  they do..*/.#ifn
385f0 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
38600 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54  DEPRECATED.SQLIT
38610 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
38620 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
38630 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
38640 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
38650 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
38660 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
38670 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
38680 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
38690 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  stmt*);.SQLITE_A
386a0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
386b0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
386c0 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
386d0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
386e0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
386f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
38700 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
38710 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
38720 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
38730 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
38740 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
3875