System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 911cb36ff8ce628b560f5e44df99193b02f4ed99:


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 36 2e 30 2e 20 20  ersion 3.16.0.  
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c  By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74  C code files int
00e0: 6f 20 74 68 69 73 0a 2a 2a 20 73 69 6e 67 6c 65  o this.** single
00f0: 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68 65   large file, the
0100: 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61 6e   entire code can
0110: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73 20   be compiled as 
0120: 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c 61  a single transla
0130: 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20 54  tion.** unit.  T
0140: 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79 20  his allows many 
0150: 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f 20  compilers to do 
0160: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74 68  optimizations th
0170: 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65 0a  at would not be.
0180: 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20 74  ** possible if t
0190: 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63 6f  he files were co
01a0: 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65 6c  mpiled separatel
01b0: 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65 20  y.  Performance 
01c0: 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a 20  improvements.** 
01d0: 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61 72  of 5% or more ar
01e0: 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e 20  e commonly seen 
01f0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
0200: 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69 6e  ompiled as a sin
0210: 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74 69  gle.** translati
0220: 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20 54  on unit..**.** T
0230: 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c 20  his file is all 
0240: 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d 70  you need to comp
0250: 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f 20  ile SQLite.  To 
0260: 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f 74  use SQLite in ot
0270: 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 2c  her.** programs,
0280: 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20 66   you need this f
0290: 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71 6c  ile and the "sql
02a0: 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20 66  ite3.h" header f
02b0: 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65 73  ile that defines
02c0: 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d 6d  .** the programm
02d0: 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ing interface to
02e0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
02f0: 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64 6f  ary.  (If you do
0300: 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 74 68 65   not have.** the
0310: 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68 65 61   "sqlite3.h" hea
0320: 64 65 72 20 66 69 6c 65 20 61 74 20 68 61 6e 64  der file at hand
0330: 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e 64 20  , you will find 
0340: 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65 64 20  a copy embedded 
0350: 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 74 65  within.** the te
0360: 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c 65 2e  xt of this file.
0370: 20 20 53 65 61 72 63 68 20 66 6f 72 20 22 42 65    Search for "Be
0380: 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 33  gin file sqlite3
0390: 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68 65 20  .h" to find the 
03a0: 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65 20  start.** of the 
03b0: 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74 65 33  embedded sqlite3
03c0: 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 2e 29  .h header file.)
03d0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f 64 65   Additional code
03e0: 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 6e 65   files may be ne
03f0: 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75 20 77  eded.** if you w
0400: 61 6e 74 20 61 20 77 72 61 70 70 65 72 20 74 6f  ant a wrapper to
0410: 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c 69 74   interface SQLit
0420: 65 20 77 69 74 68 20 79 6f 75 72 20 63 68 6f 69  e with your choi
0430: 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d 69 6e  ce of programmin
0440: 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e 20 54  g.** language. T
0450: 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65 20  he code for the 
0460: 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d 61 6e  "sqlite3" comman
0470: 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69 73 20  d-line shell is 
0480: 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73 65 70  also in a.** sep
0490: 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68 69 73  arate file. This
04a0: 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 6f   file contains o
04b0: 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74 68 65  nly code for the
04c0: 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c 69 62   core SQLite lib
04d0: 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  rary..*/.#define
04e0: 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31 0a 23   SQLITE_CORE 1.#
04f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4d  define SQLITE_AM
0500: 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23 69 66  ALGAMATION 1.#if
0510: 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52 49 56  ndef SQLITE_PRIV
0520: 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ATE.# define SQL
0530: 49 54 45 5f 50 52 49 56 41 54 45 20 73 74 61 74  ITE_PRIVATE stat
0540: 69 63 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a  ic.#endif./*****
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20  ********* Begin 
0560: 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68  file sqliteInt.h
0570: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0590: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20  ********/./*.** 
05a0: 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31  2001 September 1
05b0: 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  5.**.** The auth
05c0: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70  or disclaims cop
05d0: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73  yright to this s
05e0: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20  ource code.  In 
05f0: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65  place of.** a le
0600: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65  gal notice, here
0610: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a   is a blessing:.
0620: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  **.**    May you
0630: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74   do good and not
0640: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79   evil..**    May
0650: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76   you find forgiv
0660: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65  eness for yourse
0670: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f  lf and forgive o
0680: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79  thers..**    May
0690: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c   you share freel
06a0: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20  y, never taking 
06b0: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69  more than you gi
06c0: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ve..**.*********
06d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74  .** Internal int
0720: 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f  erface definitio
0730: 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a  ns for SQLite..*
0740: 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  *.*/.#ifndef SQL
0750: 49 54 45 49 4e 54 5f 48 0a 23 64 65 66 69 6e 65  ITEINT_H.#define
0760: 20 53 51 4c 49 54 45 49 4e 54 5f 48 0a 0a 2f 2a   SQLITEINT_H../*
0770: 20 53 70 65 63 69 61 6c 20 43 6f 6d 6d 65 6e 74   Special Comment
0780: 73 3a 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 63 6f  s:.**.** Some co
0790: 6d 6d 65 6e 74 73 20 68 61 76 65 20 73 70 65 63  mments have spec
07a0: 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 74  ial meaning to t
07b0: 68 65 20 74 6f 6f 6c 73 20 74 68 61 74 20 6d 65  he tools that me
07c0: 61 73 75 72 65 20 74 65 73 74 0a 2a 2a 20 63 6f  asure test.** co
07d0: 76 65 72 61 67 65 3a 0a 2a 2a 0a 2a 2a 20 20 20  verage:.**.**   
07e0: 20 4e 4f 5f 54 45 53 54 20 20 20 20 20 20 20 20   NO_TEST        
07f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2d 20 54               - T
0800: 68 65 20 62 72 61 6e 63 68 65 73 20 6f 6e 20 74  he branches on t
0810: 68 69 73 20 6c 69 6e 65 20 61 72 65 20 6e 6f 74  his line are not
0820: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20  .**             
0830: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0840: 20 20 20 20 20 6d 65 61 73 75 72 65 64 20 62 79       measured by
0850: 20 62 72 61 6e 63 68 20 63 6f 76 65 72 61 67 65   branch coverage
0860: 2e 20 20 54 68 69 73 20 69 73 0a 2a 2a 20 20 20  .  This is.**   
0870: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 75                 u
0890: 73 65 64 20 6f 6e 20 6c 69 6e 65 73 20 6f 66 20  sed on lines of 
08a0: 63 6f 64 65 20 74 68 61 74 20 61 63 74 75 61 6c  code that actual
08b0: 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ly.**           
08c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
08d0: 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74         implement
08e0: 20 70 61 72 74 73 20 6f 66 20 63 6f 76 65 72 61   parts of covera
08f0: 67 65 20 74 65 73 74 69 6e 67 2e 0a 2a 2a 0a 2a  ge testing..**.*
0900: 2a 20 20 20 20 4f 50 54 49 4d 49 5a 41 54 49 4f  *    OPTIMIZATIO
0910: 4e 2d 49 46 2d 54 52 55 45 20 20 20 20 20 20 20  N-IF-TRUE       
0920: 20 2d 20 54 68 69 73 20 62 72 61 6e 63 68 20 69   - This branch i
0930: 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 61 6c 77  s allowed to alw
0940: 61 79 20 62 65 20 66 61 6c 73 65 0a 2a 2a 20 20  ay be false.**  
0950: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0970: 61 6e 64 20 74 68 65 20 63 6f 72 72 65 63 74 20  and the correct 
0980: 61 6e 73 77 65 72 20 69 73 20 73 74 69 6c 6c 20  answer is still 
0990: 6f 62 74 61 69 6e 65 64 2c 0a 2a 2a 20 20 20 20  obtained,.**    
09a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
09b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 74 68                th
09c0: 6f 75 67 68 20 70 65 72 68 61 70 73 20 6d 6f 72  ough perhaps mor
09d0: 65 20 73 6c 6f 77 6c 79 2e 0a 2a 2a 0a 2a 2a 20  e slowly..**.** 
09e0: 20 20 20 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 2d     OPTIMIZATION-
09f0: 49 46 2d 46 41 4c 53 45 20 20 20 20 20 20 20 2d  IF-FALSE       -
0a00: 20 54 68 69 73 20 62 72 61 6e 63 68 20 69 73 20   This branch is 
0a10: 61 6c 6c 6f 77 65 64 20 74 6f 20 61 6c 77 61 79  allowed to alway
0a20: 20 62 65 20 74 72 75 65 0a 2a 2a 20 20 20 20 20   be true.**     
0a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0a40: 20 20 20 20 20 20 20 20 20 20 20 20 20 61 6e 64               and
0a50: 20 74 68 65 20 63 6f 72 72 65 63 74 20 61 6e 73   the correct ans
0a60: 77 65 72 20 69 73 20 73 74 69 6c 6c 20 6f 62 74  wer is still obt
0a70: 61 69 6e 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20  ained,.**       
0a80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0a90: 20 20 20 20 20 20 20 20 20 20 20 74 68 6f 75 67             thoug
0aa0: 68 20 70 65 72 68 61 70 73 20 6d 6f 72 65 20 73  h perhaps more s
0ab0: 6c 6f 77 6c 79 2e 0a 2a 2a 0a 2a 2a 20 20 20 20  lowly..**.**    
0ac0: 50 52 45 56 45 4e 54 53 2d 48 41 52 4d 4c 45 53  PREVENTS-HARMLES
0ad0: 53 2d 4f 56 45 52 52 45 41 44 20 20 2d 20 54 68  S-OVERREAD  - Th
0ae0: 69 73 20 62 72 61 6e 63 68 20 70 72 65 76 65 6e  is branch preven
0af0: 74 73 20 61 20 62 75 66 66 65 72 20 6f 76 65 72  ts a buffer over
0b00: 72 65 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  read.**         
0b10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0b20: 20 20 20 20 20 20 20 20 20 74 68 61 74 20 77 6f           that wo
0b30: 75 6c 64 20 62 65 20 68 61 72 6d 6c 65 73 73 20  uld be harmless 
0b40: 61 6e 64 20 75 6e 64 65 74 65 63 74 61 62 6c 65  and undetectable
0b50: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20  .**             
0b60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0b70: 20 20 20 20 20 69 66 20 69 74 20 64 69 64 20 6f       if it did o
0b80: 63 63 75 72 2e 20 20 0a 2a 2a 0a 2a 2a 20 49 6e  ccur.  .**.** In
0b90: 20 61 6c 6c 20 63 61 73 65 73 2c 20 74 68 65 20   all cases, the 
0ba0: 73 70 65 63 69 61 6c 20 63 6f 6d 6d 65 6e 74 20  special comment 
0bb0: 6d 75 73 74 20 62 65 20 65 6e 63 6c 6f 73 65 64  must be enclosed
0bc0: 20 69 6e 20 74 68 65 20 75 73 75 61 6c 0a 2a 2a   in the usual.**
0bd0: 20 73 6c 61 73 68 2d 61 73 74 65 72 69 73 6b 2e   slash-asterisk.
0be0: 2e 2e 61 73 74 65 72 69 73 6b 2d 73 6c 61 73 68  ..asterisk-slash
0bf0: 20 63 6f 6d 6d 65 6e 74 20 6d 61 72 6b 73 2c 20   comment marks, 
0c00: 77 69 74 68 20 6e 6f 20 73 70 61 63 65 73 20 62  with no spaces b
0c10: 65 74 77 65 65 6e 20 74 68 65 20 0a 2a 2a 20 61  etween the .** a
0c20: 73 74 65 72 69 73 6b 73 20 61 6e 64 20 74 68 65  sterisks and the
0c30: 20 63 6f 6d 6d 65 6e 74 20 74 65 78 74 2e 0a 2a   comment text..*
0c40: 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75  /../*.** Make su
0c50: 72 65 20 74 68 65 20 54 63 6c 20 63 61 6c 6c 69  re the Tcl calli
0c60: 6e 67 20 63 6f 6e 76 65 6e 74 69 6f 6e 20 6d 61  ng convention ma
0c70: 63 72 6f 20 69 73 20 64 65 66 69 6e 65 64 2e 20  cro is defined. 
0c80: 20 54 68 69 73 20 6d 61 63 72 6f 20 69 73 0a 2a   This macro is.*
0c90: 2a 20 6f 6e 6c 79 20 75 73 65 64 20 62 79 20 74  * only used by t
0ca0: 65 73 74 20 63 6f 64 65 20 61 6e 64 20 54 63 6c  est code and Tcl
0cb0: 20 69 6e 74 65 67 72 61 74 69 6f 6e 20 63 6f 64   integration cod
0cc0: 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  e..*/.#ifndef SQ
0cd0: 4c 49 54 45 5f 54 43 4c 41 50 49 0a 23 20 20 64  LITE_TCLAPI.#  d
0ce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 43 4c  efine SQLITE_TCL
0cf0: 41 50 49 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  API.#endif../*.*
0d00: 2a 20 4d 61 6b 65 20 73 75 72 65 20 74 68 61 74  * Make sure that
0d10: 20 72 61 6e 64 5f 73 28 29 20 69 73 20 61 76 61   rand_s() is ava
0d20: 69 6c 61 62 6c 65 20 6f 6e 20 57 69 6e 64 6f 77  ilable on Window
0d30: 73 20 73 79 73 74 65 6d 73 20 77 69 74 68 20 4d  s systems with M
0d40: 53 56 43 20 32 30 30 35 0a 2a 2a 20 6f 72 20 68  SVC 2005.** or h
0d50: 69 67 68 65 72 2e 0a 2a 2f 0a 23 69 66 20 64 65  igher..*/.#if de
0d60: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20  fined(_MSC_VER) 
0d70: 26 26 20 5f 4d 53 43 5f 56 45 52 3e 3d 31 34 30  && _MSC_VER>=140
0d80: 30 0a 23 20 20 64 65 66 69 6e 65 20 5f 43 52 54  0.#  define _CRT
0d90: 5f 52 41 4e 44 5f 53 0a 23 65 6e 64 69 66 0a 0a  _RAND_S.#endif..
0da0: 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68  /*.** Include th
0db0: 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 75 73  e header file us
0dc0: 65 64 20 74 6f 20 63 75 73 74 6f 6d 69 7a 65 20  ed to customize 
0dd0: 74 68 65 20 63 6f 6d 70 69 6c 65 72 20 6f 70 74  the compiler opt
0de0: 69 6f 6e 73 20 66 6f 72 20 4d 53 56 43 2e 0a 2a  ions for MSVC..*
0df0: 2a 20 54 68 69 73 20 73 68 6f 75 6c 64 20 62 65  * This should be
0e00: 20 64 6f 6e 65 20 66 69 72 73 74 20 73 6f 20 74   done first so t
0e10: 68 61 74 20 69 74 20 63 61 6e 20 73 75 63 63 65  hat it can succe
0e20: 73 73 66 75 6c 6c 79 20 70 72 65 76 65 6e 74 20  ssfully prevent 
0e30: 73 70 75 72 69 6f 75 73 0a 2a 2a 20 63 6f 6d 70  spurious.** comp
0e40: 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 20 64 75  iler warnings du
0e50: 65 20 74 6f 20 73 75 62 73 65 71 75 65 6e 74 20  e to subsequent 
0e60: 63 6f 6e 74 65 6e 74 20 69 6e 20 74 68 69 73 20  content in this 
0e70: 66 69 6c 65 20 61 6e 64 20 6f 74 68 65 72 20 66  file and other f
0e80: 69 6c 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  iles.** that are
0e90: 20 69 6e 63 6c 75 64 65 64 20 62 79 20 74 68 69   included by thi
0ea0: 73 20 66 69 6c 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  s file..*/./****
0eb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75  ********** Inclu
0ec0: 64 65 20 6d 73 76 63 2e 68 20 69 6e 20 74 68 65  de msvc.h in the
0ed0: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74   middle of sqlit
0ee0: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
0ef0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a  *********/./****
0f00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e  ********** Begin
0f10: 20 66 69 6c 65 20 6d 73 76 63 2e 68 20 2a 2a 2a   file msvc.h ***
0f20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0f30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0f40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a  *********/./*.**
0f50: 20 32 30 31 35 20 4a 61 6e 75 61 72 79 20 31 32   2015 January 12
0f60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0f70: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0f80: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0f90: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0fa0: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0fb0: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0fc0: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0fd0: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0fe0: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
0ff0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
1000: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
1010: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
1020: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
1030: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
1040: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
1050: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
1060: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
1070: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
1080: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1090: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
10a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
10b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
10c0: 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ****.**.** This 
10d0: 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 63 6f  file contains co
10e0: 64 65 20 74 68 61 74 20 69 73 20 73 70 65 63 69  de that is speci
10f0: 66 69 63 20 74 6f 20 4d 53 56 43 2e 0a 2a 2f 0a  fic to MSVC..*/.
1100: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  #ifndef SQLITE_M
1110: 53 56 43 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  SVC_H.#define SQ
1120: 4c 49 54 45 5f 4d 53 56 43 5f 48 0a 0a 23 69 66  LITE_MSVC_H..#if
1130: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45   defined(_MSC_VE
1140: 52 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  R).#pragma warni
1150: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 30 35  ng(disable : 405
1160: 34 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  4).#pragma warni
1170: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 30 35  ng(disable : 405
1180: 35 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  5).#pragma warni
1190: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 30  ng(disable : 410
11a0: 30 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  0).#pragma warni
11b0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 32  ng(disable : 412
11c0: 37 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  7).#pragma warni
11d0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 33  ng(disable : 413
11e0: 30 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  0).#pragma warni
11f0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 35  ng(disable : 415
1200: 32 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  2).#pragma warni
1210: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 38  ng(disable : 418
1220: 39 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  9).#pragma warni
1230: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 30  ng(disable : 420
1240: 36 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  6).#pragma warni
1250: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 31  ng(disable : 421
1260: 30 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  0).#pragma warni
1270: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 33  ng(disable : 423
1280: 32 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  2).#pragma warni
1290: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 34  ng(disable : 424
12a0: 34 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  4).#pragma warni
12b0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 33 30  ng(disable : 430
12c0: 35 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  5).#pragma warni
12d0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 33 30  ng(disable : 430
12e0: 36 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  6).#pragma warni
12f0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 37 30  ng(disable : 470
1300: 32 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  2).#pragma warni
1310: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 37 30  ng(disable : 470
1320: 36 29 0a 23 65 6e 64 69 66 20 2f 2a 20 64 65 66  6).#endif /* def
1330: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 2a  ined(_MSC_VER) *
1340: 2f 0a 0a 23 65 6e 64 69 66 20 2f 2a 20 53 51 4c  /..#endif /* SQL
1350: 49 54 45 5f 4d 53 56 43 5f 48 20 2a 2f 0a 0a 2f  ITE_MSVC_H */../
1360: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45  ************** E
1370: 6e 64 20 6f 66 20 6d 73 76 63 2e 68 20 2a 2a 2a  nd of msvc.h ***
1380: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1390: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
13b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43  ************** C
13c0: 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72 65 20  ontinuing where 
13d0: 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e 20 73  we left off in s
13e0: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a  qliteInt.h *****
13f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a  *************/..
1400: 2f 2a 0a 2a 2a 20 53 70 65 63 69 61 6c 20 73 65  /*.** Special se
1410: 74 75 70 20 66 6f 72 20 56 78 57 6f 72 6b 73 0a  tup for VxWorks.
1420: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
1430: 2a 2a 20 49 6e 63 6c 75 64 65 20 76 78 77 6f 72  ** Include vxwor
1440: 6b 73 2e 68 20 69 6e 20 74 68 65 20 6d 69 64 64  ks.h in the midd
1450: 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 6e 74 2e  le of sqliteInt.
1460: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  h **************
1470: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
1480: 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 76 78  ** Begin file vx
1490: 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a  works.h ********
14a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
14b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
14c0: 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 31 35 2d 30 33  */./*.** 2015-03
14d0: 2d 30 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  -02.**.** The au
14e0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
14f0: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
1500: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
1510: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
1520: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
1530: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
1540: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
1550: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
1560: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
1570: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
1580: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
1590: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
15a0: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
15b0: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
15c0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
15d0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
15e0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
15f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1600: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1630: 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68  *******.**.** Th
1640: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
1650: 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 73 70   code that is sp
1660: 65 63 69 66 69 63 20 74 6f 20 57 69 6e 64 20 52  ecific to Wind R
1670: 69 76 65 72 27 73 20 56 78 57 6f 72 6b 73 0a 2a  iver's VxWorks.*
1680: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f  /.#if defined(__
1690: 52 54 50 5f 5f 29 20 7c 7c 20 64 65 66 69 6e 65  RTP__) || define
16a0: 64 28 5f 57 52 53 5f 4b 45 52 4e 45 4c 29 0a 2f  d(_WRS_KERNEL)./
16b0: 2a 20 54 68 69 73 20 69 73 20 56 78 57 6f 72 6b  * This is VxWork
16c0: 73 2e 20 20 53 65 74 20 75 70 20 74 68 69 6e 67  s.  Set up thing
16d0: 73 20 73 70 65 63 69 61 6c 6c 79 20 66 6f 72 20  s specially for 
16e0: 74 68 61 74 20 4f 53 0a 2a 2f 0a 23 69 6e 63 6c  that OS.*/.#incl
16f0: 75 64 65 20 3c 76 78 57 6f 72 6b 73 2e 68 3e 0a  ude <vxWorks.h>.
1700: 23 69 6e 63 6c 75 64 65 20 3c 70 74 68 72 65 61  #include <pthrea
1710: 64 2e 68 3e 20 20 2f 2a 20 61 6d 61 6c 67 61 6d  d.h>  /* amalgam
1720: 61 74 6f 72 3a 20 64 6f 6e 74 63 61 63 68 65 20  ator: dontcache 
1730: 2a 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f 56 58  */.#define OS_VX
1740: 57 4f 52 4b 53 20 31 0a 23 64 65 66 69 6e 65 20  WORKS 1.#define 
1750: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 20  SQLITE_OS_OTHER 
1760: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
1770: 5f 48 4f 4d 45 47 52 4f 57 4e 5f 52 45 43 55 52  _HOMEGROWN_RECUR
1780: 53 49 56 45 5f 4d 55 54 45 58 20 31 0a 23 64 65  SIVE_MUTEX 1.#de
1790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fine SQLITE_OMIT
17a0: 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20  _LOAD_EXTENSION 
17b0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
17c0: 5f 45 4e 41 42 4c 45 5f 4c 4f 43 4b 49 4e 47 5f  _ENABLE_LOCKING_
17d0: 53 54 59 4c 45 20 30 0a 23 64 65 66 69 6e 65 20  STYLE 0.#define 
17e0: 48 41 56 45 5f 55 54 49 4d 45 20 31 0a 23 65 6c  HAVE_UTIME 1.#el
17f0: 73 65 0a 2f 2a 20 54 68 69 73 20 69 73 20 6e 6f  se./* This is no
1800: 74 20 56 78 57 6f 72 6b 73 2e 20 2a 2f 0a 23 64  t VxWorks. */.#d
1810: 65 66 69 6e 65 20 4f 53 5f 56 58 57 4f 52 4b 53  efine OS_VXWORKS
1820: 20 30 0a 23 64 65 66 69 6e 65 20 48 41 56 45 5f   0.#define HAVE_
1830: 46 43 48 4f 57 4e 20 31 0a 23 64 65 66 69 6e 65  FCHOWN 1.#define
1840: 20 48 41 56 45 5f 52 45 41 44 4c 49 4e 4b 20 31   HAVE_READLINK 1
1850: 0a 23 64 65 66 69 6e 65 20 48 41 56 45 5f 4c 53  .#define HAVE_LS
1860: 54 41 54 20 31 0a 23 65 6e 64 69 66 20 2f 2a 20  TAT 1.#endif /* 
1870: 64 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 52  defined(_WRS_KER
1880: 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a  NEL) */../******
1890: 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 20 6f 66 20  ******** End of 
18a0: 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a 2a 2a  vxworks.h ******
18b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18d0: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  *******/./******
18e0: 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e 74 69 6e 75  ******** Continu
18f0: 69 6e 67 20 77 68 65 72 65 20 77 65 20 6c 65 66  ing where we lef
1900: 74 20 6f 66 66 20 69 6e 20 73 71 6c 69 74 65 49  t off in sqliteI
1910: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  nt.h ***********
1920: 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  *******/../*.** 
1930: 54 68 65 73 65 20 23 64 65 66 69 6e 65 73 20 73  These #defines s
1940: 68 6f 75 6c 64 20 65 6e 61 62 6c 65 20 3e 32 47  hould enable >2G
1950: 42 20 66 69 6c 65 20 73 75 70 70 6f 72 74 20 6f  B file support o
1960: 6e 20 50 4f 53 49 58 20 69 66 20 74 68 65 0a 2a  n POSIX if the.*
1970: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  * underlying ope
1980: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 73 75  rating system su
1990: 70 70 6f 72 74 73 20 69 74 2e 20 20 49 66 20 74  pports it.  If t
19a0: 68 65 20 4f 53 20 6c 61 63 6b 73 0a 2a 2a 20 6c  he OS lacks.** l
19b0: 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72  arge file suppor
19c0: 74 2c 20 6f 72 20 69 66 20 74 68 65 20 4f 53 20  t, or if the OS 
19d0: 69 73 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 73  is windows, thes
19e0: 65 20 73 68 6f 75 6c 64 20 62 65 20 6e 6f 2d 6f  e should be no-o
19f0: 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 69 63 6b 65 74  ps..**.** Ticket
1a00: 20 23 32 37 33 39 3a 20 20 54 68 65 20 5f 4c 41   #2739:  The _LA
1a10: 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 20 6d  RGEFILE_SOURCE m
1a20: 61 63 72 6f 20 6d 75 73 74 20 61 70 70 65 61 72  acro must appear
1a30: 20 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a 20 73   before any.** s
1a40: 79 73 74 65 6d 20 23 69 6e 63 6c 75 64 65 73 2e  ystem #includes.
1a50: 20 20 48 65 6e 63 65 2c 20 74 68 69 73 20 62 6c    Hence, this bl
1a60: 6f 63 6b 20 6f 66 20 63 6f 64 65 20 6d 75 73 74  ock of code must
1a70: 20 62 65 20 74 68 65 20 76 65 72 79 20 66 69 72   be the very fir
1a80: 73 74 0a 2a 2a 20 63 6f 64 65 20 69 6e 20 61 6c  st.** code in al
1a90: 6c 20 73 6f 75 72 63 65 20 66 69 6c 65 73 2e 0a  l source files..
1aa0: 2a 2a 0a 2a 2a 20 4c 61 72 67 65 20 66 69 6c 65  **.** Large file
1ab0: 20 73 75 70 70 6f 72 74 20 63 61 6e 20 62 65 20   support can be 
1ac0: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 74  disabled using t
1ad0: 68 65 20 2d 44 53 51 4c 49 54 45 5f 44 49 53 41  he -DSQLITE_DISA
1ae0: 42 4c 45 5f 4c 46 53 20 73 77 69 74 63 68 0a 2a  BLE_LFS switch.*
1af0: 2a 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  * on the compile
1b00: 72 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65 2e 20  r command line. 
1b10: 20 54 68 69 73 20 69 73 20 6e 65 63 65 73 73 61   This is necessa
1b20: 72 79 20 69 66 20 79 6f 75 20 61 72 65 20 63 6f  ry if you are co
1b30: 6d 70 69 6c 69 6e 67 0a 2a 2a 20 6f 6e 20 61 20  mpiling.** on a 
1b40: 72 65 63 65 6e 74 20 6d 61 63 68 69 6e 65 20 28  recent machine (
1b50: 65 78 3a 20 52 65 64 20 48 61 74 20 37 2e 32 29  ex: Red Hat 7.2)
1b60: 20 62 75 74 20 79 6f 75 20 77 61 6e 74 20 79 6f   but you want yo
1b70: 75 72 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  ur code to work.
1b80: 2a 2a 20 6f 6e 20 61 6e 20 6f 6c 64 65 72 20 6d  ** on an older m
1b90: 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20  achine (ex: Red 
1ba0: 48 61 74 20 36 2e 30 29 2e 20 20 49 66 20 79 6f  Hat 6.0).  If yo
1bb0: 75 20 63 6f 6d 70 69 6c 65 20 6f 6e 20 52 65 64  u compile on Red
1bc0: 20 48 61 74 20 37 2e 32 0a 2a 2a 20 77 69 74 68   Hat 7.2.** with
1bd0: 6f 75 74 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c  out this option,
1be0: 20 4c 46 53 20 69 73 20 65 6e 61 62 6c 65 2e 20   LFS is enable. 
1bf0: 20 42 75 74 20 4c 46 53 20 64 6f 65 73 20 6e 6f   But LFS does no
1c00: 74 20 65 78 69 73 74 20 69 6e 20 74 68 65 20 6b  t exist in the k
1c10: 65 72 6e 65 6c 0a 2a 2a 20 69 6e 20 52 65 64 20  ernel.** in Red 
1c20: 48 61 74 20 36 2e 30 2c 20 73 6f 20 74 68 65 20  Hat 6.0, so the 
1c30: 63 6f 64 65 20 77 6f 6e 27 74 20 77 6f 72 6b 2e  code won't work.
1c40: 20 20 48 65 6e 63 65 2c 20 66 6f 72 20 6d 61 78    Hence, for max
1c50: 69 6d 75 6d 20 62 69 6e 61 72 79 0a 2a 2a 20 70  imum binary.** p
1c60: 6f 72 74 61 62 69 6c 69 74 79 20 79 6f 75 20 73  ortability you s
1c70: 68 6f 75 6c 64 20 6f 6d 69 74 20 4c 46 53 2e 0a  hould omit LFS..
1c80: 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 76 69 6f  **.** The previo
1c90: 75 73 20 70 61 72 61 67 72 61 70 68 20 77 61 73  us paragraph was
1ca0: 20 77 72 69 74 74 65 6e 20 69 6e 20 32 30 30 35   written in 2005
1cb0: 2e 20 20 28 54 68 69 73 20 70 61 72 61 67 72 61  .  (This paragra
1cc0: 70 68 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  ph is written.**
1cd0: 20 6f 6e 20 32 30 30 38 2d 31 31 2d 32 38 2e 29   on 2008-11-28.)
1ce0: 20 54 68 65 73 65 20 64 61 79 73 2c 20 61 6c 6c   These days, all
1cf0: 20 4c 69 6e 75 78 20 6b 65 72 6e 65 6c 73 20 73   Linux kernels s
1d00: 75 70 70 6f 72 74 20 6c 61 72 67 65 20 66 69 6c  upport large fil
1d10: 65 73 2c 20 73 6f 0a 2a 2a 20 79 6f 75 20 73 68  es, so.** you sh
1d20: 6f 75 6c 64 20 70 72 6f 62 61 62 6c 79 20 6c 65  ould probably le
1d30: 61 76 65 20 4c 46 53 20 65 6e 61 62 6c 65 64 2e  ave LFS enabled.
1d40: 20 20 42 75 74 20 73 6f 6d 65 20 65 6d 62 65 64    But some embed
1d50: 64 65 64 20 70 6c 61 74 66 6f 72 6d 73 20 6d 69  ded platforms mi
1d60: 67 68 74 0a 2a 2a 20 6c 61 63 6b 20 4c 46 53 20  ght.** lack LFS 
1d70: 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
1d80: 65 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45  e SQLITE_DISABLE
1d90: 5f 4c 46 53 20 6d 61 63 72 6f 20 6d 69 67 68 74  _LFS macro might
1da0: 20 73 74 69 6c 6c 20 62 65 20 75 73 65 66 75 6c   still be useful
1db0: 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d 69 6c 61 72 20  ..**.** Similar 
1dc0: 69 73 20 74 72 75 65 20 66 6f 72 20 4d 61 63 20  is true for Mac 
1dd0: 4f 53 20 58 2e 20 20 4c 46 53 20 69 73 20 6f 6e  OS X.  LFS is on
1de0: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20  ly supported on 
1df0: 4d 61 63 20 4f 53 20 58 20 39 20 61 6e 64 20 6c  Mac OS X 9 and l
1e00: 61 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  ater..*/.#ifndef
1e10: 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f   SQLITE_DISABLE_
1e20: 4c 46 53 0a 23 20 64 65 66 69 6e 65 20 5f 4c 41  LFS.# define _LA
1e30: 52 47 45 5f 46 49 4c 45 20 20 20 20 20 20 20 31  RGE_FILE       1
1e40: 0a 23 20 69 66 6e 64 65 66 20 5f 46 49 4c 45 5f  .# ifndef _FILE_
1e50: 4f 46 46 53 45 54 5f 42 49 54 53 0a 23 20 20 20  OFFSET_BITS.#   
1e60: 64 65 66 69 6e 65 20 5f 46 49 4c 45 5f 4f 46 46  define _FILE_OFF
1e70: 53 45 54 5f 42 49 54 53 20 36 34 0a 23 20 65 6e  SET_BITS 64.# en
1e80: 64 69 66 0a 23 20 64 65 66 69 6e 65 20 5f 4c 41  dif.# define _LA
1e90: 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 20 31  RGEFILE_SOURCE 1
1ea0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 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 5b 76 65 72 73 69 6f 6e 20   Since [version 
35e0: 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65 6f 66  3.6.18] ([dateof
35f0: 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a 20 53  :3.6.18]), .** S
3600: 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64  QLite source cod
3610: 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65  e has been store
3620: 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68  d in the.** <a h
3630: 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e  ref="http://www.
3640: 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22  fossil-scm.org/"
3650: 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72  >Fossil configur
3660: 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74  ation management
3670: 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20  .** system</a>. 
3680: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55   ^The SQLITE_SOU
3690: 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61  RCE_ID macro eva
36a0: 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73  luates to.** a s
36b0: 74 72 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e  tring which iden
36c0: 74 69 66 69 65 73 20 61 20 70 61 72 74 69 63 75  tifies a particu
36d0: 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20  lar check-in of 
36e0: 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e  SQLite.** within
36f0: 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69   its configurati
3700: 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79  on management sy
3710: 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49  stem.  ^The SQLI
3720: 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20  TE_SOURCE_ID.** 
3730: 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20  string contains 
3740: 74 68 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d  the date and tim
3750: 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69  e of the check-i
3760: 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53  n (UTC) and an S
3770: 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74  HA1.** hash of t
3780: 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65  he entire source
3790: 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   tree..**.** See
37a0: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
37b0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a  libversion()],.*
37c0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  * [sqlite3_libve
37d0: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c  rsion_number()],
37e0: 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65   [sqlite3_source
37f0: 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  id()],.** [sqlit
3800: 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64  e_version()] and
3810: 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f   [sqlite_source_
3820: 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  id()]..*/.#defin
3830: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
3840: 20 20 20 20 20 20 20 20 22 33 2e 31 36 2e 30 22          "3.16.0"
3850: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3860: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33  VERSION_NUMBER 3
3870: 30 31 36 30 30 30 0a 23 64 65 66 69 6e 65 20 53  016000.#define S
3880: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20  QLITE_SOURCE_ID 
3890: 20 20 20 20 20 22 32 30 31 36 2d 31 32 2d 33 30       "2016-12-30
38a0: 20 31 37 3a 34 30 3a 31 34 20 31 34 64 38 35 35   17:40:14 14d855
38b0: 64 32 62 32 62 35 62 33 34 38 35 65 30 36 37 33  d2b2b5b3485e0673
38c0: 64 31 31 34 30 35 64 62 37 32 36 36 62 33 34 63  d11405db7266b34c
38d0: 36 64 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  6d"../*.** CAPI3
38e0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
38f0: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
3900: 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  mbers.** KEYWORD
3910: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
3920: 6f 6e 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  on sqlite3_sourc
3930: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  eid.**.** These 
3940: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69  interfaces provi
3950: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  de the same info
3960: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b  rmation as the [
3970: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c  SQLITE_VERSION],
3980: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
3990: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64  ION_NUMBER], and
39a0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
39b0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
39c0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74  or macros.** but
39d0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20   are associated 
39e0: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
39f0: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
3a00: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28  header file.  ^(
3a10: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67  Cautious.** prog
3a20: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e  rammers might in
3a30: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73  clude assert() s
3a40: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
3a50: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
3a60: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74  o.** verify that
3a70: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
3a80: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66   by these interf
3a90: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d  aces match the m
3aa0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20  acros in.** the 
3ab0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73  header, and thus
3ac0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
3ad0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a   application is.
3ae0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
3af0: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72   matching librar
3b00: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c  y and header fil
3b10: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  es..**.** <block
3b20: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61  quote><pre>.** a
3b30: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c  ssert( sqlite3_l
3b40: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
3b50: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49  ()==SQLITE_VERSI
3b60: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20  ON_NUMBER );.** 
3b70: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
3b80: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
3b90: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  ),SQLITE_SOURCE_
3ba0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73  ID)==0 );.** ass
3bb0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
3bc0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
3bd0: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29  ,SQLITE_VERSION)
3be0: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ==0 );.** </pre>
3bf0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
3c00: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3c10: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
3c20: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e  ing constant con
3c30: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f  tains the text o
3c40: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  f [SQLITE_VERSIO
3c50: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54  N].** macro.  ^T
3c60: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
3c70: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e  rsion() function
3c80: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
3c90: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20  er to the.** to 
3ca0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  the sqlite3_vers
3cb0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
3cc0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  stant.  The sqli
3cd0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
3ce0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
3cf0: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65  provided for use
3d00: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44   in DLLs since D
3d10: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79  LL users usually
3d20: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20   do not have.** 
3d30: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
3d40: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
3d50: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c  s within the DLL
3d60: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
3d70: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
3d80: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20  mber() function 
3d90: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
3da0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b  er equal to.** [
3db0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
3dc0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71  UMBER].  ^The sq
3dd0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
3de0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
3df0: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
3e00: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73  to a string cons
3e10: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65  tant whose value
3e20: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
3e30: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
3e40: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
3e50: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e  processor macro.
3e60: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
3e70: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   [sqlite_version
3e80: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f  ()] and [sqlite_
3e90: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f  source_id()]..*/
3ea0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
3eb0: 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76  t char sqlite3_v
3ec0: 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54  ersion[] = SQLIT
3ed0: 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54  E_VERSION;.SQLIT
3ee0: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
3ef0: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
3f00: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  sion(void);.SQLI
3f10: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
3f20: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
3f30: 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  eid(void);.SQLIT
3f40: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
3f50: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
3f60: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ber(void);../*.*
3f70: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
3f80: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d  Time Library Com
3f90: 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  pilation Options
3fa0: 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a   Diagnostics.**.
3fb0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
3fc0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
3fd0: 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  ed() function re
3fe0: 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a  turns 0 or 1 .**
3ff0: 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74   indicating whet
4000: 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65  her the specifie
4010: 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66  d option was def
4020: 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70  ined at .** comp
4030: 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  ile time.  ^The 
4040: 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d  SQLITE_ prefix m
4050: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72  ay be omitted fr
4060: 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f  om the .** optio
4070: 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f  n name passed to
4080: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
4090: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20  option_used().  
40a0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
40b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
40c0: 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  n_get() function
40d0: 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e   allows iteratin
40e0: 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69  g.** over the li
40f0: 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68  st of options th
4100: 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20  at were defined 
4110: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20  at compile time 
4120: 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20  by.** returning 
4130: 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65  the N-th compile
4140: 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72   time option str
4150: 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f  ing.  ^If N is o
4160: 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20  ut of range,.** 
4170: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
4180: 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75  ption_get() retu
4190: 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
41a0: 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  er.  ^The SQLITE
41b0: 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20  _ .** prefix is 
41c0: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79  omitted from any
41d0: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
41e0: 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
41f0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
4200: 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70  et()..**.** ^Sup
4210: 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61  port for the dia
4220: 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  gnostic function
4230: 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  s sqlite3_compil
4240: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a  eoption_used().*
4250: 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
4260: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
4270: 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  ) may be omitted
4280: 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74   by specifying t
4290: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
42a0: 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f  MIT_COMPILEOPTIO
42b0: 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20  N_DIAGS] option 
42c0: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
42d0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
42e0: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b   SQL functions [
42f0: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
4300: 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64  tion_used()] and
4310: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  .** [sqlite_comp
4320: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d  ileoption_get()]
4330: 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c   and the [compil
4340: 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61  e_options pragma
4350: 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  ]..*/.#ifndef SQ
4360: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
4370: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51  EOPTION_DIAGS.SQ
4380: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
4390: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
43a0: 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68  on_used(const ch
43b0: 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53  ar *zOptName);.S
43c0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
43d0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
43e0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
43f0: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
4400: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4410: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
4420: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
4430: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
4440: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
4450: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
4460: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
4470: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
4480: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
4490: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
44a0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
44b0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
44c0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
44d0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
44e0: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
44f0: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
4500: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
4510: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
4520: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
4530: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
4540: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
4550: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
4560: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
4570: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
4580: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
4590: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
45a0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
45b0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
45c0: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
45d0: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
45e0: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
45f0: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
4600: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
4610: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
4620: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
4630: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
4640: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
4650: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
4660: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
4670: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
4680: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
4690: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
46a0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
46b0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
46c0: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
46d0: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
46e0: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
46f0: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
4700: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
4710: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
4720: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
4730: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
4740: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
4750: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
4760: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
4770: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
4780: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
4790: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
47a0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
47b0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
47c0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
47d0: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
47e0: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
47f0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
4800: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
4810: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
4820: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
4830: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
4840: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
4850: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
4860: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
4870: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
4880: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
4890: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
48a0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
48b0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
48c0: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
48d0: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
48e0: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
48f0: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
4900: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
4910: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
4920: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
4930: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
4940: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
4950: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
4960: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
4970: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
4980: 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72  LIZED].  ^(The r
4990: 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
49a0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68  he.** sqlite3_th
49b0: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
49c0: 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74  ion shows only t
49d0: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
49e0: 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68  setting of.** th
49f0: 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74  read safety, not
4a00: 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68   any run-time ch
4a10: 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65  anges to that se
4a20: 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a  tting made by.**
4a30: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
4a40: 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ). In other word
4a50: 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  s, the return va
4a60: 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
4a70: 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a  _threadsafe().**
4a80: 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79   is unchanged by
4a90: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
4aa0: 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a  3_config().)^.**
4ab0: 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72  .** See the [thr
4ac0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63  eading mode] doc
4ad0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
4ae0: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
4af0: 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ation..*/.SQLITE
4b00: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
4b10: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
4b20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
4b30: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
4b40: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
4b50: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
4b60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4b70: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
4b80: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
4b90: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
4ba0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
4bb0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
4bc0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
4bd0: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
4be0: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
4bf0: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
4c00: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
4c10: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
4c20: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
4c30: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
4c40: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
4c50: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
4c60: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
4c70: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
4c80: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
4c90: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
4ca0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
4cb0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
4cc0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
4cd0: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
4ce0: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
4cf0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
4d00: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
4d10: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
4d20: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
4d30: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
4d40: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
4d50: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
4d60: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
4d70: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
4d80: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
4d90: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
4da0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
4db0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
4dc0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
4dd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4de0: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
4df0: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
4e00: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
4e10: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
4e20: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
4e30: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
4e40: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
4e50: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
4e60: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
4e70: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
4e80: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
4e90: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
4ea0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
4eb0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
4ec0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
4ed0: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
4ee0: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
4ef0: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
4f00: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
4f10: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
4f20: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
4f30: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
4f40: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
4f50: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
4f60: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
4f70: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
4f80: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
4f90: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
4fa0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
4fb0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
4fc0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
4fd0: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
4fe0: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
4ff0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
5000: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
5010: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
5020: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
5030: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
5040: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
5050: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
5060: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
5070: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
5080: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
5090: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
50a0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
50b0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
50c0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
50d0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
50e0: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
50f0: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
5100: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
5110: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
5120: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
5130: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
5140: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
5150: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
5160: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
5170: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
5180: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
5190: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
51a0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
51b0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
51c0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
51d0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
51e0: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
51f0: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
5200: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
5210: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
5220: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
5230: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
5240: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
5250: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
5260: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
5270: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
5280: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
5290: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
52a0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
52b0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
52c0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
52d0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
52e0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
52f0: 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ion.** DESTRUCTO
5300: 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  R: sqlite3.**.**
5310: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c   ^The sqlite3_cl
5320: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
5330: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75  3_close_v2() rou
5340: 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72 75  tines are destru
5350: 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ctors.** for the
5360: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
5370: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
5380: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
5390: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
53a0: 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53  e_v2() return [S
53b0: 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20  QLITE_OK] if.** 
53c0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
53d0: 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73 66  ject is successf
53e0: 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61  ully destroyed a
53f0: 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65  nd all associate
5400: 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61  d.** resources a
5410: 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a  re deallocated..
5420: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61  **.** ^If the da
5430: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
5440: 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  n is associated 
5450: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
5460: 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
5470: 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e  tements or unfin
5480: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
5490: 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65  ckup objects the
54a0: 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  n sqlite3_close(
54b0: 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20  ).** will leave 
54c0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
54d0: 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64  nection open and
54e0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
54f0: 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  BUSY]..** ^If sq
5500: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
5510: 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
5520: 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70  unfinalized prep
5530: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a  ared statements.
5540: 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69  ** and/or unfini
5550: 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63  shed sqlite3_bac
5560: 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64  kups, then the d
5570: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
5580: 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e  on becomes.** an
5590: 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69   unusable "zombi
55a0: 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75  e" which will au
55b0: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64  tomatically be d
55c0: 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20  eallocated when 
55d0: 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70  the.** last prep
55e0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
55f0: 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74  s finalized or t
5600: 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f  he last sqlite3_
5610: 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e  backup is.** fin
5620: 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69  ished.  The sqli
5630: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
5640: 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65  nterface is inte
5650: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74  nded for use wit
5660: 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61  h.** host langua
5670: 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72  ges that are gar
5680: 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20  bage collected, 
5690: 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72  and where the or
56a0: 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  der in which.** 
56b0: 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20  destructors are 
56c0: 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72  called is arbitr
56d0: 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  ary..**.** Appli
56e0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b  cations should [
56f0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
5700: 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c   | finalize] all
5710: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
5720: 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ments],.** [sqli
5730: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
5740: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
5750: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20  B handles], and 
5760: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
5770: 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e  kup_finish | fin
5780: 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65  ish] all [sqlite
5790: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
57a0: 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  s associated.** 
57b0: 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65  with the [sqlite
57c0: 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20  3] object prior 
57d0: 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f  to attempting to
57e0: 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63   close the objec
57f0: 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74  t.  ^If.** sqlit
5800: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73  e3_close_v2() is
5810: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
5820: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
5830: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
5840: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
5850: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
5860: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
5870: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
5880: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
5890: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
58a0: 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  it returns [SQLI
58b0: 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64  TE_OK] and the d
58c0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
58d0: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
58e0: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
58f0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
5900: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
5910: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
5920: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
5930: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
5940: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
5950: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
5960: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
5970: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
5980: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
5990: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
59a0: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
59b0: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
59c0: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
59d0: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
59e0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
59f0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
5a00: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
5a10: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
5a20: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
5a30: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
5a40: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
5a50: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
5a60: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
5a70: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
5a80: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
5a90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
5aa0: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
5ab0: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
5ac0: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
5ad0: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
5ae0: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
5af0: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
5b00: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
5b10: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
5b20: 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  p..*/.SQLITE_API
5b30: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f   int sqlite3_clo
5b40: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  se(sqlite3*);.SQ
5b50: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
5b60: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71  ite3_close_v2(sq
5b70: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
5b80: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
5b90: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
5ba0: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
5bb0: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
5bc0: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
5bd0: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
5be0: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
5bf0: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
5c00: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
5c10: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69  pedef int (*sqli
5c20: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
5c30: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
5c40: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
5c50: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
5c60: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
5c70: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20  on Interface.** 
5c80: 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
5c90: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
5ca0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
5cb0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
5cc0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
5cd0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
5ce0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
5cf0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
5d00: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
5d10: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
5d20: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
5d30: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
5d40: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
5d50: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
5d60: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
5d70: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
5d80: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
5d90: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
5da0: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
5db0: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
5dc0: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
5dd0: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
5de0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
5df0: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
5e00: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
5e10: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
5e20: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
5e30: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
5e40: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
5e50: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
5e60: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
5e70: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
5e80: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
5e90: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
5ea0: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
5eb0: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
5ec0: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
5ed0: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
5ee0: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
5ef0: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
5f00: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
5f10: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
5f20: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
5f30: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
5f40: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
5f50: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
5f60: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
5f70: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
5f80: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
5f90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
5fa0: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
5fb0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
5fc0: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
5fd0: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
5fe0: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
5ff0: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
6000: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
6010: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
6020: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
6030: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
6040: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
6050: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
6060: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
6070: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
6080: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
6090: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
60a0: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
60b0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
60c0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
60d0: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
60e0: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
60f0: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
6100: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
6110: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
6120: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
6130: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
6140: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
6150: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
6160: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
6170: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
6180: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
6190: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
61a0: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
61b0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
61c0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
61d0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
61e0: 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  f.** sqlite3_exe
61f0: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72  c() after the er
6200: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
6210: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ng is no longer 
6220: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  needed..** ^If t
6230: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
6240: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
6250: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  () is not NULL a
6260: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  nd no errors.** 
6270: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69  occur, then sqli
6280: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20  te3_exec() sets 
6290: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69  the pointer in i
62a0: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  ts 5th parameter
62b0: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f   to.** NULL befo
62c0: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
62d0: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74  .** ^If an sqlit
62e0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
62f0: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
6300: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ero, the sqlite3
6310: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69  _exec().** routi
6320: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  ne returns SQLIT
6330: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20  E_ABORT without 
6340: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c  invoking the cal
6350: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a  lback again and.
6360: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69  ** without runni
6370: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ng any subsequen
6380: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
6390: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64  ..**.** ^The 2nd
63a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
63b0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
63c0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
63d0: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  n is the.** numb
63e0: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
63f0: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54   the result.  ^T
6400: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
6410: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
6420: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63  xec().** callbac
6430: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
6440: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
6450: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73  ings obtained as
6460: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c   if from.** [sql
6470: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
6480: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63  ()], one for eac
6490: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61  h column.  ^If a
64a0: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a  n element of a.*
64b0: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20  * result row is 
64c0: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
64d0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69  rresponding stri
64e0: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  ng pointer for t
64f0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
6500: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
6510: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
6520: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
6530: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71  ent to the.** sq
6540: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
6550: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
6560: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
6570: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65   strings where e
6580: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70  ach.** entry rep
6590: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65  resents the name
65a0: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e   of correspondin
65b0: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  g result column 
65c0: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  as obtained.** f
65d0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
65e0: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a  umn_name()]..**.
65f0: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70  ** ^If the 2nd p
6600: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
6610: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20  te3_exec() is a 
6620: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20  NULL pointer, a 
6630: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e  pointer.** to an
6640: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f   empty string, o
6650: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  r a pointer that
6660: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77   contains only w
6670: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72  hitespace and/or
6680: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74   .** SQL comment
6690: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73  s, then no SQL s
66a0: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76  tatements are ev
66b0: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20  aluated and the 
66c0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e  database.** is n
66d0: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
66e0: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a  * Restrictions:.
66f0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
6700: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
6710: 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20 74  on must ensure t
6720: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61  hat the 1st para
6730: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
6740: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20  _exec().**      
6750: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f  is a valid and o
6760: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
6770: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c  nnection]..** <l
6780: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
6790: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  on must not clos
67a0: 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
67b0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
67c0: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
67d0: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
67e0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
67f0: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
6800: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
6810: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ning..** <li> Th
6820: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
6830: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  st not modify th
6840: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
6850: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f  text passed into
6860: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64  .**      the 2nd
6870: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
6880: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
6890: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
68a0: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
68b0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ul>.*/.SQLITE
68c0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
68d0: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
68e0: 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  *,              
68f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6900: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
6910: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
6920: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
6930: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6940: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
6950: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
6960: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
6970: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
6980: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
6990: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
69a0: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  void *,
69b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
69c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
69d0: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
69e0: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
69f0: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
6a00: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
6a10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6a20: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
6a30: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
6a40: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6a50: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
6a60: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75   KEYWORDS: {resu
6a70: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
6a80: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  ons}.**.** Many 
6a90: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
6aa0: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
6ab0: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
6ac0: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
6ad0: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
6ae0: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
6af0: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
6b00: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
6b10: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
6b20: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
6b30: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
6b40: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
6b50: 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  so: [extended re
6b60: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
6b70: 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e  tions].*/.#defin
6b80: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
6b90: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
6ba0: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
6bb0: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
6bc0: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
6bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6be0: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
6bf0: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
6c00: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
6c10: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
6c20: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
6c30: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
6c40: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
6c50: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
6c60: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
6c70: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
6c80: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
6c90: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
6ca0: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
6cb0: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
6cc0: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
6cd0: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
6ce0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6cf0: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
6d00: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
6d10: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
6d20: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
6d30: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
6d40: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
6d50: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
6d60: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
6d70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
6d80: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
6d90: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
6da0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
6db0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
6dc0: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
6dd0: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
6de0: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
6df0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6e00: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
6e10: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
6e20: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
6e30: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
6e40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6e50: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
6e60: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
6e70: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
6e80: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
6e90: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
6ea0: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
6eb0: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
6ec0: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
6ed0: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
6ee0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
6ef0: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
6f00: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
6f10: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
6f20: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6f30: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
6f40: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
6f50: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
6f60: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
6f70: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
6f80: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
6f90: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
6fa0: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
6fb0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
6fc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
6fd0: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
6fe0: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
6ff0: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
7000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
7010: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
7020: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65  /* Database is e
7030: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  mpty */.#define 
7040: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
7050: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
7060: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
7070: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
7080: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
7090: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
70a0: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
70b0: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
70c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
70d0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
70e0: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
70f0: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
7100: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
7110: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
7120: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
7130: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
7140: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7150: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
7160: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
7170: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
7180: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7190: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
71a0: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
71b0: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
71c0: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
71d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
71e0: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
71f0: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
7200: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
7210: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
7220: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
7230: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
7240: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
7250: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
7260: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
7270: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
7280: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
7290: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
72a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
72b0: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
72c0: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
72d0: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
72e0: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
72f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
7300: 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20 2f  TICE      27   /
7310: 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20  * Notifications 
7320: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
7330: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
7340: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20  LITE_WARNING    
7350: 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67   28   /* Warning
7360: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
7370: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
7380: 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20  SQLITE_ROW      
7390: 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74     100  /* sqlit
73a0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e  e3_step() has an
73b0: 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79 20  other row ready 
73c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
73d0: 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30  E_DONE        10
73e0: 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  1  /* sqlite3_st
73f0: 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68 65  ep() has finishe
7400: 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f  d executing */./
7410: 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63  * end-of-error-c
7420: 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  odes */../*.** C
7430: 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65  API3REF: Extende
7440: 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  d Result Codes.*
7450: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74  * KEYWORDS: {ext
7460: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
7470: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a  e definitions}.*
7480: 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61  *.** In its defa
7490: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
74a0: 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f  n, SQLite API ro
74b0: 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e  utines return on
74c0: 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a  e of 30 integer.
74d0: 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  ** [result codes
74e0: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
74f0: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
7500: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
7510: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
7520: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
7530: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
7540: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
7550: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
7560: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
7570: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
7580: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
7590: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
75a0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
75b0: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
75c0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
75d0: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64 61  ersion 3.3.8 [da
75e0: 74 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20 61  teof:3.3.8].** a
75f0: 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64  nd later) includ
7600: 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72  e.** support for
7610: 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75   additional resu
7620: 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70 72  lt codes that pr
7630: 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69  ovide more detai
7640: 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  led information.
7650: 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e  ** about errors.
7660: 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65 64   These [extended
7670: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 61   result codes] a
7680: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
7690: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
76a0: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
76b0: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
76c0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
76d0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
76e0: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
76f0: 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e 64    Or, the extend
7700: 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20 74  ed code for.** t
7710: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
7720: 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74 61  rror can be obta
7730: 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ined using.** [s
7740: 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
7750: 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23  errcode()]..*/.#
7760: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7770: 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20 20  ERR_READ        
7780: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
7790: 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ERR | (1<<8)).#d
77a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
77b0: 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20 20  RR_SHORT_READ   
77c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
77d0: 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  RR | (2<<8)).#de
77e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
77f0: 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20 20  R_WRITE         
7800: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7810: 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  R | (3<<8)).#def
7820: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7830: 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  _FSYNC          
7840: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7850: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
7860: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
7870: 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  DIR_FSYNC       
7880: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
7890: 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (5<<8)).#defin
78a0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 54  e SQLITE_IOERR_T
78b0: 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20 20  RUNCATE         
78c0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
78d0: 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (6<<8)).#define
78e0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53   SQLITE_IOERR_FS
78f0: 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20 20  TAT             
7900: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
7910: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
7920: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e 4c  SQLITE_IOERR_UNL
7930: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
7940: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
7950: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
7960: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c 4f  QLITE_IOERR_RDLO
7970: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28 53  CK            (S
7980: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 39  QLITE_IOERR | (9
7990: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
79a0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
79b0: 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  E            (SQ
79c0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 30  LITE_IOERR | (10
79d0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
79e0: 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
79f0: 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ED           (SQ
7a00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 31  LITE_IOERR | (11
7a10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7a20: 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d  LITE_IOERR_NOMEM
7a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7a40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 32  LITE_IOERR | (12
7a50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7a60: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45 53  LITE_IOERR_ACCES
7a70: 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  S            (SQ
7a80: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 33  LITE_IOERR | (13
7a90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7aa0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43 4b  LITE_IOERR_CHECK
7ab0: 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53 51  RESERVEDLOCK (SQ
7ac0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 34  LITE_IOERR | (14
7ad0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7ae0: 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20  LITE_IOERR_LOCK 
7af0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7b00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 35  LITE_IOERR | (15
7b10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53 45  LITE_IOERR_CLOSE
7b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 36  LITE_IOERR | (16
7b50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7b60: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 43  LITE_IOERR_DIR_C
7b70: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53 51  LOSE         (SQ
7b80: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 37  LITE_IOERR | (17
7b90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7ba0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f 50  LITE_IOERR_SHMOP
7bb0: 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53 51  EN           (SQ
7bc0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 38  LITE_IOERR | (18
7bd0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7be0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53 49  LITE_IOERR_SHMSI
7bf0: 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53 51  ZE           (SQ
7c00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 39  LITE_IOERR | (19
7c10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7c20: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f  LITE_IOERR_SHMLO
7c30: 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53 51  CK           (SQ
7c40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 30  LITE_IOERR | (20
7c50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7c60: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d 41  LITE_IOERR_SHMMA
7c70: 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  P            (SQ
7c80: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 31  LITE_IOERR | (21
7c90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7ca0: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b 20  LITE_IOERR_SEEK 
7cb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7cc0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 32  LITE_IOERR | (22
7cd0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7ce0: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45 54  LITE_IOERR_DELET
7cf0: 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53 51  E_NOENT      (SQ
7d00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 33  LITE_IOERR | (23
7d10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7d20: 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50 20  LITE_IOERR_MMAP 
7d30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7d40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 34  LITE_IOERR | (24
7d50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7d60: 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54 45  LITE_IOERR_GETTE
7d70: 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53 51  MPPATH       (SQ
7d80: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 35  LITE_IOERR | (25
7d90: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7da0: 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56 50  LITE_IOERR_CONVP
7db0: 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53 51  ATH          (SQ
7dc0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 36  LITE_IOERR | (26
7dd0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7de0: 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44 45  LITE_IOERR_VNODE
7df0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7e00: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 37  LITE_IOERR | (27
7e10: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7e20: 4c 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48 20  LITE_IOERR_AUTH 
7e30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7e40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 38  LITE_IOERR | (28
7e50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7e60: 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41 52  LITE_LOCKED_SHAR
7e70: 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53 51  EDCACHE      (SQ
7e80: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20 28  LITE_LOCKED |  (
7e90: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
7ea0: 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f 56  QLITE_BUSY_RECOV
7eb0: 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28 53  ERY           (S
7ec0: 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20 20  QLITE_BUSY   |  
7ed0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
7ee0: 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41 50  SQLITE_BUSY_SNAP
7ef0: 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20 28  SHOT           (
7f00: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
7f10: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
7f20: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
7f30: 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20 20  _NOTEMPDIR      
7f40: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
7f50: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
7f60: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
7f70: 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20 20  EN_ISDIR        
7f80: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
7f90: 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  EN | (2<<8)).#de
7fa0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
7fb0: 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20 20  OPEN_FULLPATH   
7fc0: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
7fd0: 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OPEN | (3<<8)).#
7fe0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
7ff0: 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48 20  NTOPEN_CONVPATH 
8000: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
8010: 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29 29  NTOPEN | (4<<8))
8020: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8030: 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20  CORRUPT_VTAB    
8040: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
8050: 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29  CORRUPT | (1<<8)
8060: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
8070: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
8080: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
8090: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (1<<
80a0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
80b0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54  TE_READONLY_CANT
80c0: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
80d0: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
80e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
80f0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f  LITE_READONLY_RO
8100: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53 51  LLBACK       (SQ
8110: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
8120: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
8130: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
8140: 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20 28  DBMOVED        (
8150: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
8160: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
8170: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52  e SQLITE_ABORT_R
8180: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20  OLLBACK         
8190: 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c   (SQLITE_ABORT |
81a0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
81b0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
81c0: 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20 20  NT_CHECK        
81d0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
81e0: 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NT | (1<<8)).#de
81f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
8200: 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f  TRAINT_COMMITHOO
8210: 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  K   (SQLITE_CONS
8220: 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29 29  TRAINT | (2<<8))
8230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8240: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45 49  CONSTRAINT_FOREI
8250: 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f  GNKEY   (SQLITE_
8260: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33 3c  CONSTRAINT | (3<
8270: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
8280: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46  ITE_CONSTRAINT_F
8290: 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51 4c  UNCTION     (SQL
82a0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
82b0: 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (4<<8)).#define
82c0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
82d0: 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20 20  NT_NOTNULL      
82e0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
82f0: 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  NT | (5<<8)).#de
8300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
8310: 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b 45  TRAINT_PRIMARYKE
8320: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
8330: 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29 29  TRAINT | (6<<8))
8340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8350: 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47 47  CONSTRAINT_TRIGG
8360: 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ER      (SQLITE_
8370: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37 3c  CONSTRAINT | (7<
8380: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
8390: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 55  ITE_CONSTRAINT_U
83a0: 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51 4c  NIQUE       (SQL
83b0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
83c0: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
83d0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
83e0: 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  NT_VTAB         
83f0: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
8400: 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  NT | (9<<8)).#de
8410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
8420: 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20 20  TRAINT_ROWID    
8430: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
8440: 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29 29  TRAINT |(10<<8))
8450: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8460: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 57  NOTICE_RECOVER_W
8470: 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  AL      (SQLITE_
8480: 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29 29  NOTICE | (1<<8))
8490: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
84a0: 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f 52  NOTICE_RECOVER_R
84b0: 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45 5f  OLLBACK (SQLITE_
84c0: 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29 29  NOTICE | (2<<8))
84d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
84e0: 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44 45  WARNING_AUTOINDE
84f0: 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  X       (SQLITE_
8500: 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38 29  WARNING | (1<<8)
8510: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
8520: 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20 20  _AUTH_USER      
8530: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
8540: 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29 0a  _AUTH | (1<<8)).
8550: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
8560: 4b 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e 54  K_LOAD_PERMANENT
8570: 4c 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4f  LY     (SQLITE_O
8580: 4b 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  K | (1<<8))../*.
8590: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
85a0: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
85b0: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
85c0: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
85d0: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
85e0: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
85f0: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
8600: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
8610: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
8620: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
8630: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
8640: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
8650: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
8660: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
8670: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
8680: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
8690: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
86a0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
86b0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
86c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
86d0: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
86e0: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
86f0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8700: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8710: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
8720: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
8730: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
8740: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8750: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8760: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
8770: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
8780: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
8790: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
87a0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
87b0: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
87c0: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
87d0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
87e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
87f0: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
8800: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
8810: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8820: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
8830: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
8840: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
8850: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8860: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8870: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
8880: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
8890: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
88a0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
88b0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
88c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
88d0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
88e0: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
88f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8900: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
8910: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
8920: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
8930: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8940: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
8950: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
8960: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
8970: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8980: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
8990: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
89a0: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
89b0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
89c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
89d0: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
89e0: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
89f0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8a00: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
8a10: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
8a20: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
8a30: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8a40: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
8a50: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
8a60: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
8a70: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8a80: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
8a90: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
8aa0: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
8ab0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8ac0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8ad0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
8ae0: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
8af0: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
8b00: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8b10: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8b20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
8b30: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
8b40: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
8b50: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8b60: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8b70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
8b80: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
8b90: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
8ba0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8bb0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8bc0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
8bd0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
8be0: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
8bf0: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
8c00: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
8c10: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
8c20: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
8c30: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
8c40: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
8c50: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
8c60: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
8c70: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
8c80: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
8c90: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
8ca0: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
8cb0: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
8cc0: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
8cd0: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
8ce0: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
8cf0: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
8d00: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
8d10: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
8d20: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
8d30: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
8d40: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
8d50: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
8d60: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8d70: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
8d80: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
8d90: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
8da0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8db0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8dc0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8dd0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8de0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
8df0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
8e00: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
8e10: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
8e20: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
8e30: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8e40: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8e50: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
8e60: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8e70: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
8e80: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
8e90: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
8ea0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8eb0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8ec0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8ed0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8ee0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
8ef0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
8f00: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
8f10: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
8f20: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
8f30: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8f40: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8f50: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
8f60: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
8f70: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
8f80: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
8f90: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
8fa0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
8fb0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
8fc0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8fd0: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
8fe0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
8ff0: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
9000: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
9010: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
9020: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
9030: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
9040: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
9050: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
9060: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
9070: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
9080: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
9090: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
90a0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
90b0: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
90c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
90d0: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
90e0: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
90f0: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
9100: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
9110: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
9120: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
9130: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
9140: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
9150: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
9160: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
9170: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
9180: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
9190: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
91a0: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
91b0: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
91c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
91d0: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
91e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
91f0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
9200: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
9210: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
9220: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
9230: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
9240: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
9250: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
9260: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9270: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
9280: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
9290: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
92a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
92b0: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
92c0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
92d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
92e0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
92f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
9300: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
9310: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
9320: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
9330: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
9340: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
9350: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
9360: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
9370: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
9380: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
9390: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
93a0: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
93b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
93c0: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
93d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
93e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
93f0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
9400: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
9410: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
9420: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
9430: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
9440: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
9450: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
9460: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
9470: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
9480: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
9490: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
94a0: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
94b0: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
94c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
94d0: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
94e0: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
94f0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
9500: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
9510: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
9520: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
9530: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
9540: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
9550: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
9560: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
9570: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
9580: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
9590: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
95a0: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
95b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
95c0: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
95d0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
95e0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
95f0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
9600: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
9610: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
9620: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
9630: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
9640: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
9650: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
9660: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
9670: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
9680: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
9690: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
96a0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
96b0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
96c0: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
96d0: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
96e0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
96f0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
9700: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
9710: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
9720: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
9730: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
9740: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
9750: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
9760: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
9770: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
9780: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
9790: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
97a0: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
97b0: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
97c0: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
97d0: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
97e0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
97f0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
9800: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
9810: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
9820: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
9830: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
9840: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
9850: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
9860: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
9870: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
9880: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
9890: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
98a0: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
98b0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
98c0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
98d0: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
98e0: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
98f0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
9900: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
9910: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
9920: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
9930: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
9940: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
9950: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
9960: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
9970: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
9980: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
9990: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
99a0: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
99b0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
99c0: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
99d0: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
99e0: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
99f0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
9a00: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
9a10: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
9a20: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
9a30: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
9a40: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
9a50: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
9a60: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
9a70: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
9a80: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
9a90: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
9aa0: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
9ab0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
9ac0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
9ad0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
9ae0: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
9af0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
9b00: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
9b10: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
9b20: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
9b30: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
9b40: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
9b50: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
9b60: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
9b70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
9b80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
9b90: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
9ba0: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
9bb0: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
9bc0: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
9bd0: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
9be0: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
9bf0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
9c00: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
9c10: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
9c20: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
9c30: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
9c40: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
9c50: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
9c60: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
9c70: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
9c80: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
9c90: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
9ca0: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
9cb0: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
9cc0: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
9cd0: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
9ce0: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
9cf0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
9d00: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
9d10: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
9d20: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
9d30: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
9d40: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
9d50: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
9d60: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
9d70: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
9d80: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
9d90: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
9da0: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
9db0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
9dc0: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
9dd0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
9de0: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
9df0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
9e00: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
9e10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9e20: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
9e30: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
9e40: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
9e50: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
9e60: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
9e70: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
9e80: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
9e90: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9ea0: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
9eb0: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
9ec0: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
9ed0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9ee0: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
9ef0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
9f00: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
9f10: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
9f20: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
9f30: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
9f40: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
9f50: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
9f60: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
9f70: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
9f80: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
9f90: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
9fa0: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
9fb0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
9fc0: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
9fd0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
9fe0: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
9ff0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
a000: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
a010: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
a020: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
a030: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
a040: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
a050: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
a060: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
a070: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
a080: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
a090: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
a0a0: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
a0b0: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
a0c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
a0d0: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
a0e0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
a0f0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
a100: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
a110: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
a120: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
a130: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
a140: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
a150: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
a160: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
a170: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
a180: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
a190: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
a1a0: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
a1b0: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
a1c0: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
a1d0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
a1e0: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
a1f0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
a200: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
a210: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
a220: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
a230: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
a240: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
a250: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
a260: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
a270: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
a280: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
a290: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
a2a0: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
a2b0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
a2c0: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
a2d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
a2e0: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
a2f0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
a300: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
a310: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
a320: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
a330: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
a340: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
a350: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
a360: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
a370: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
a380: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
a390: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
a3a0: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
a3b0: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
a3c0: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
a3d0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
a3e0: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
a3f0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
a400: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
a410: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
a420: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
a430: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
a440: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
a450: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
a460: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
a470: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
a480: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
a490: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
a4a0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
a4b0: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
a4c0: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
a4d0: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
a4e0: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
a4f0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
a500: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
a510: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
a520: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
a530: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
a540: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
a550: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
a560: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
a570: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
a580: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
a590: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
a5a0: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
a5b0: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
a5c0: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
a5d0: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
a5e0: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
a5f0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
a600: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
a610: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
a620: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
a630: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
a640: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
a650: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
a660: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
a670: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
a680: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
a690: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
a6a0: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
a6b0: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
a6c0: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
a6d0: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
a6e0: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
a6f0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
a700: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
a710: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
a720: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
a730: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
a740: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
a750: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
a760: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
a770: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
a780: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
a790: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
a7a0: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
a7b0: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
a7c0: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
a7d0: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
a7e0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
a7f0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
a800: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
a810: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
a820: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
a830: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
a840: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
a850: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
a860: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
a870: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
a880: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
a890: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
a8a0: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
a8b0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
a8c0: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
a8d0: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
a8e0: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
a8f0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
a900: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
a910: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
a920: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
a930: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
a940: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
a950: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
a960: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
a970: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
a980: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
a990: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
a9a0: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
a9b0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
a9c0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
a9d0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
a9e0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
a9f0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
aa00: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
aa10: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
aa20: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
aa30: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
aa40: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
aa50: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
aa60: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
aa70: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
aa80: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
aa90: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
aaa0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
aab0: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
aac0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
aad0: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
aae0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
aaf0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
ab00: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
ab10: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
ab20: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
ab30: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
ab40: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
ab50: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
ab60: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
ab70: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
ab80: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
ab90: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
aba0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
abb0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
abc0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
abd0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
abe0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
abf0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
ac00: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
ac10: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
ac20: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
ac30: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
ac40: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
ac50: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
ac60: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
ac70: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
ac80: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
ac90: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
aca0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
acb0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
acc0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
acd0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
ace0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
acf0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
ad00: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
ad10: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
ad20: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
ad30: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
ad40: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
ad50: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
ad60: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
ad70: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
ad80: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
ad90: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
ada0: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
adb0: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
adc0: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
add0: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
ade0: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
adf0: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
ae00: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
ae10: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
ae20: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
ae30: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
ae40: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
ae50: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
ae60: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
ae70: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
ae80: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
ae90: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
aea0: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
aeb0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
aec0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
aed0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
aee0: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
aef0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
af00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
af10: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
af20: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
af30: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
af40: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
af50: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
af60: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
af70: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
af80: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
af90: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
afa0: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
afb0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
afc0: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
afd0: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
afe0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
aff0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
b000: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
b010: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
b020: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
b030: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
b040: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
b050: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
b060: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
b070: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
b080: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
b090: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
b0a0: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
b0b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
b0c0: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
b0d0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
b0e0: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
b0f0: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
b100: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
b110: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
b120: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
b130: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
b140: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
b150: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
b160: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
b170: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
b180: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
b190: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
b1a0: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
b1b0: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
b1c0: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
b1d0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
b1e0: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
b1f0: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
b200: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
b210: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
b220: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
b230: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
b240: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
b250: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
b260: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
b270: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
b280: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
b290: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
b2a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
b2b0: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
b2c0: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
b2d0: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
b2e0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
b2f0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
b300: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
b310: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
b320: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
b330: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
b340: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
b350: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
b360: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
b370: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
b380: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
b390: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
b3a0: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
b3b0: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
b3c0: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
b3d0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
b3e0: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
b3f0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
b400: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
b410: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
b420: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
b430: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
b440: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
b450: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
b460: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
b470: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
b480: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
b490: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
b4a0: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
b4b0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b4c0: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
b4d0: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
b4e0: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
b4f0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
b500: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
b510: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
b520: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
b530: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
b540: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
b550: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
b560: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
b570: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
b580: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
b590: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
b5a0: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
b5b0: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
b5c0: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
b5d0: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
b5e0: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
b5f0: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
b600: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
b610: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
b620: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
b630: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
b640: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
b650: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
b660: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
b670: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b680: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
b690: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b6a0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
b6b0: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
b6c0: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
b6d0: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
b6e0: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
b6f0: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
b700: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
b710: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
b720: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
b730: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
b740: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
b750: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
b760: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
b770: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
b780: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
b790: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
b7a0: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
b7b0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
b7c0: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
b7d0: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
b7e0: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
b7f0: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
b800: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
b810: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
b820: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b830: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
b840: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b850: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
b860: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
b870: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
b880: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
b890: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
b8a0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b8b0: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
b8c0: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
b8d0: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
b8e0: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
b8f0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
b900: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
b910: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
b920: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
b930: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
b940: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
b950: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
b960: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
b970: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
b980: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
b990: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
b9a0: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
b9b0: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
b9c0: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
b9d0: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
b9e0: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
b9f0: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
ba00: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
ba10: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
ba20: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
ba30: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
ba40: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ba50: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
ba60: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
ba70: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
ba80: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
ba90: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
baa0: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
bab0: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
bac0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
bad0: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73  ection.  See als
bae0: 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  o [SQLITE_FCNTL_
baf0: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
bb00: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
bb10: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e  LITE_FCNTL_JOURN
bb20: 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  AL_POINTER]].** 
bb30: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bb40: 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45  L_JOURNAL_POINTE
bb50: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
bb60: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
bb70: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
bb80: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
bb90: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
bba0: 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61   with the journa
bbb0: 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a  l file (either.*
bbc0: 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20  * the [rollback 
bbd0: 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20  journal] or the 
bbe0: 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67  [write-ahead log
bbf0: 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ]) for a particu
bc00: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
bc10: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
bc20: 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43   also [SQLITE_FC
bc30: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
bc40: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
bc50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
bc60: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f  _OMITTED]].** No
bc70: 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a   longer in use..
bc80: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
bc90: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a  TE_FCNTL_SYNC]].
bca0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bcb0: 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64  CNTL_SYNC] opcod
bcc0: 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69  e is generated i
bcd0: 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c  nternally by SQL
bce0: 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20  ite and.** sent 
bcf0: 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64  to the VFS immed
bd00: 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68  iately before th
bd10: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69  e xSync method i
bd20: 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a  s invoked on a.*
bd30: 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  * database file 
bd40: 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20  descriptor. Or, 
bd50: 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  if the xSync met
bd60: 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b  hod is not invok
bd70: 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74  ed .** because t
bd80: 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66  he user has conf
bd90: 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69  igured SQLite wi
bda0: 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73  th .** [PRAGMA s
bdb0: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
bdc0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
bdd0: 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b  OFF] it is invok
bde0: 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20  ed in place .** 
bdf0: 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  of the xSync met
be00: 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73  hod. In most cas
be10: 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20  es, the pointer 
be20: 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
be30: 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c  with.** this fil
be40: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c  e-control is NUL
be50: 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74  L. However, if t
be60: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
be70: 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64   is being synced
be80: 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61  .** as part of a
be90: 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20   multi-database 
bea0: 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75  commit, the argu
beb0: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
bec0: 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
bed0: 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69  ** string contai
bee0: 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63  ning the transac
bef0: 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75  tions master-jou
bf00: 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20  rnal file name. 
bf10: 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64  VFSes that .** d
bf20: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
bf30: 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69  signal should si
bf40: 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68  lently ignore th
bf50: 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69  is opcode. Appli
bf60: 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75  cations .** shou
bf70: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
bf80: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
bf90: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f  l()] with this o
bfa0: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
bfb0: 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70  o may .** disrup
bfc0: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
bfd0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
bfe0: 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f  ed VFSes that do
bff0: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
c000: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c010: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
c020: 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65  HASETWO]].** The
c030: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
c040: 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20  OMMIT_PHASETWO] 
c050: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
c060: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
c070: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
c080: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
c090: 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74  after a transact
c0a0: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  ion has been com
c0b0: 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65  mitted immediate
c0c0: 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65  ly.** but before
c0d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
c0e0: 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73   unlocked. VFSes
c0f0: 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65   that do not nee
c100: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a  d this signal.**
c110: 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79   should silently
c120: 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63   ignore this opc
c130: 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e  ode. Application
c140: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
c150: 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  l.** [sqlite3_fi
c160: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
c170: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
c180: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
c190: 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f  isrupt the .** o
c1a0: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
c1b0: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
c1c0: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
c1d0: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
c1e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
c1f0: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
c200: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
c210: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
c220: 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69  _RETRY] opcode i
c230: 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67  s used to config
c240: 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a  ure automatic.**
c250: 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e   retry counts an
c260: 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20  d intervals for 
c270: 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f  certain disk I/O
c280: 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20   operations for 
c290: 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b  the.** windows [
c2a0: 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  VFS] in order to
c2b0: 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e   provide robustn
c2c0: 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65  ess in the prese
c2d0: 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76  nce of.** anti-v
c2e0: 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20  irus programs.  
c2f0: 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20  By default, the 
c300: 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c  windows VFS will
c310: 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64   retry file read
c320: 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c  ,.** file write,
c330: 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65   and file delete
c340: 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74   operations up t
c350: 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68  o 10 times, with
c360: 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32   a delay.** of 2
c370: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62  5 milliseconds b
c380: 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20  efore the first 
c390: 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74  retry and with t
c3a0: 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73  he delay increas
c3b0: 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64  ing.** by an add
c3c0: 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69  itional 25 milli
c3d0: 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63  seconds with eac
c3e0: 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74  h subsequent ret
c3f0: 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ry.  This.** opc
c400: 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65  ode allows these
c410: 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20   two values (10 
c420: 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d  retries and 25 m
c430: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64  illiseconds of d
c440: 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61  elay).** to be a
c450: 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61  djusted.  The va
c460: 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64  lues are changed
c470: 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73   for all databas
c480: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a  e connections.**
c490: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
c4a0: 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61   process.  The a
c4b0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
c4c0: 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79  nter to an array
c4d0: 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67   of two.** integ
c4e0: 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69  ers where the fi
c4f0: 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68  rst integer i th
c500: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
c510: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
c520: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
c530: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
c540: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
c550: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
c560: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
c570: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
c580: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
c590: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
c5a0: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
c5b0: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
c5c0: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
c5d0: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
c5e0: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
c5f0: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
c600: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
c610: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
c620: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
c630: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
c640: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
c650: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
c660: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
c670: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
c680: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
c690: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
c6a0: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
c6b0: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
c6c0: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
c6d0: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
c6e0: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
c6f0: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
c700: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
c710: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
c720: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
c730: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
c740: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
c750: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
c760: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
c770: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
c780: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
c790: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
c7a0: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
c7b0: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
c7c0: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
c7d0: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
c7e0: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
c7f0: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
c800: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
c810: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
c820: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
c830: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
c840: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
c850: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
c860: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
c870: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
c880: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
c890: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
c8a0: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
c8b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
c8c0: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
c8d0: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
c8e0: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
c8f0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
c900: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
c910: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
c920: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
c930: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
c940: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
c950: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
c960: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
c970: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
c980: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
c990: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
c9a0: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
c9b0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
c9c0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
c9d0: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
c9e0: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
c9f0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ca00: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
ca10: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
ca20: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ca30: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
ca40: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
ca50: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
ca60: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
ca70: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
ca80: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
ca90: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
caa0: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
cab0: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
cac0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
cad0: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
cae0: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
caf0: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
cb00: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
cb10: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
cb20: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
cb30: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
cb40: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
cb50: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
cb60: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
cb70: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
cb80: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
cb90: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
cba0: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
cbb0: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
cbc0: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
cbd0: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
cbe0: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
cbf0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
cc00: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
cc10: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
cc20: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
cc30: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
cc40: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
cc50: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
cc60: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
cc70: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
cc80: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
cc90: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
cca0: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
ccb0: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
ccc0: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
ccd0: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
cce0: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
ccf0: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
cd00: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
cd10: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
cd20: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
cd30: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
cd40: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
cd50: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
cd60: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
cd70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
cd80: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
cd90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
cda0: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
cdb0: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
cdc0: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
cdd0: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
cde0: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
cdf0: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
ce00: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
ce10: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
ce20: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
ce30: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
ce40: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
ce50: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
ce60: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
ce70: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
ce80: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
ce90: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
cea0: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
ceb0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
cec0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
ced0: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
cee0: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
cef0: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
cf00: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
cf10: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
cf20: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
cf30: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
cf40: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
cf50: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
cf60: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
cf70: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
cf80: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
cf90: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
cfa0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
cfb0: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
cfc0: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
cfd0: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
cfe0: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
cff0: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
d000: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
d010: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
d020: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
d030: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d040: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
d050: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  INTER]].** ^The 
d060: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
d070: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  S_POINTER] opcod
d080: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65  e finds a pointe
d090: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
d0a0: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75  el.** [VFSes] cu
d0b0: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20  rrently in use. 
d0c0: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20   ^(The argument 
d0d0: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  X in.** sqlite3_
d0e0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c  file_control(db,
d0f0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
d100: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74  _POINTER,X) must
d110: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22   be.** of type "
d120: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a  [sqlite3_vfs] **
d130: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73  ".  This opcodes
d140: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20   will set *X.** 
d150: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  to a pointer to 
d160: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46  the top-level VF
d170: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  S.)^.** ^When th
d180: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65  ere are multiple
d190: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68   VFS shims in th
d1a0: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70  e stack, this op
d1b0: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a  code finds the.*
d1c0: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69  * upper-most shi
d1d0: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  m only..**.** <l
d1e0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
d1f0: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
d200: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
d210: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
d220: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
d230: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
d240: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
d250: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
d260: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
d270: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
d280: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
d290: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
d2a0: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
d2b0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
d2c0: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
d2d0: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
d2e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
d2f0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
d300: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
d310: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
d320: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
d330: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
d340: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
d350: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
d360: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
d370: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
d380: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
d390: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
d3a0: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
d3b0: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
d3c0: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
d3d0: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
d3e0: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
d3f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
d400: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
d410: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
d420: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
d430: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
d440: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
d450: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
d460: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
d470: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
d480: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
d490: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
d4a0: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
d4b0: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
d4c0: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
d4d0: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
d4e0: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
d4f0: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
d500: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
d510: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
d520: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
d530: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
d540: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
d550: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
d560: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
d570: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
d580: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
d590: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
d5a0: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
d5b0: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
d5c0: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
d5d0: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
d5e0: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
d5f0: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
d600: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
d610: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
d620: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
d630: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
d640: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
d650: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
d660: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
d670: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
d680: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
d690: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
d6a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
d6b0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
d6c0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
d6d0: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
d6e0: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
d6f0: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
d700: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
d710: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
d720: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
d730: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
d740: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
d750: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
d760: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
d770: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
d780: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
d790: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
d7a0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
d7b0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
d7c0: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
d7d0: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
d7e0: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
d7f0: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
d800: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
d810: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
d820: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
d830: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
d840: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
d850: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
d860: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
d870: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
d880: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
d890: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
d8a0: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
d8b0: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
d8c0: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
d8d0: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
d8e0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
d8f0: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
d900: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
d910: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
d920: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
d930: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
d940: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
d950: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
d960: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
d970: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
d980: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
d990: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
d9a0: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
d9b0: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
d9c0: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
d9d0: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
d9e0: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
d9f0: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
da00: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
da10: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
da20: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
da30: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
da40: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
da50: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
da60: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
da70: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
da80: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
da90: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
daa0: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
dab0: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
dac0: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
dad0: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
dae0: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
daf0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
db00: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
db10: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
db20: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
db30: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
db40: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
db50: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
db60: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
db70: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
db80: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
db90: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
dba0: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
dbb0: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
dbc0: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
dbd0: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
dbe0: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
dbf0: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
dc00: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
dc10: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
dc20: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
dc30: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
dc40: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
dc50: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
dc60: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
dc70: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
dc80: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
dc90: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
dca0: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
dcb0: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
dcc0: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
dcd0: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
dce0: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
dcf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
dd00: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
dd10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
dd20: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
dd30: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
dd40: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
dd50: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
dd60: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
dd70: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
dd80: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
dd90: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
dda0: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
ddb0: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
ddc0: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
ddd0: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
dde0: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
ddf0: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
de00: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
de10: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
de20: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
de30: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
de40: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
de50: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
de60: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
de70: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
de80: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
de90: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
dea0: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
deb0: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
dec0: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
ded0: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
dee0: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
def0: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
df00: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
df10: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
df20: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
df30: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
df40: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
df50: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
df60: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
df70: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
df80: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
df90: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
dfa0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
dfb0: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
dfc0: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
dfd0: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
dfe0: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
dff0: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
e000: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
e010: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
e020: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
e030: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
e040: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
e050: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
e060: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
e070: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
e080: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
e090: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
e0a0: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
e0b0: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
e0c0: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
e0d0: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
e0e0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
e0f0: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
e100: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
e110: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
e120: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
e130: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
e140: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
e150: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
e160: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
e170: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
e180: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
e190: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
e1a0: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
e1b0: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
e1c0: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
e1d0: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
e1e0: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
e1f0: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
e200: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
e210: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
e220: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
e230: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_GET_HANDLE]].
e240: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
e250: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
e260: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61  ANDLE] opcode ca
e270: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
e280: 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72  ain the.** under
e290: 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c  lying native fil
e2a0: 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61  e handle associa
e2b0: 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20  ted with a file 
e2c0: 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69  handle.  This fi
e2d0: 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e  le.** control in
e2e0: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
e2f0: 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74  ument as a point
e300: 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66  er to a native f
e310: 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a  ile handle and.*
e320: 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73  * writes the res
e330: 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65  ulting value the
e340: 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  re..**.** <li>[[
e350: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
e360: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
e370: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
e380: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
e390: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
e3a0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
e3b0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
e3c0: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
e3d0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
e3e0: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
e3f0: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
e400: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
e410: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
e420: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
e430: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
e440: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
e450: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
e460: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
e470: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
e480: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
e490: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
e4a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
e4b0: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
e4c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
e4d0: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
e4e0: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
e4f0: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
e500: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
e510: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
e520: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
e530: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
e540: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
e550: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
e560: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
e570: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
e580: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
e590: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
e5a0: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
e5b0: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
e5c0: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
e5d0: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
e5e0: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
e5f0: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
e600: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
e610: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
e620: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
e630: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
e640: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
e650: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
e660: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
e670: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
e680: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
e690: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
e6a0: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
e6b0: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
e6c0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
e6d0: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
e6e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
e6f0: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
e700: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
e710: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
e720: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
e730: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
e740: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
e750: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
e760: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
e770: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
e780: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
e790: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e7a0: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
e7b0: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
e7c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
e7d0: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
e7e0: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  E       2.#defin
e7f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
e800: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
e810: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
e820: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
e830: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
e840: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
e850: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
e860: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
e870: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
e880: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
e890: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
e8a0: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
e8b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
e8c0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
e8d0: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
e8e0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
e8f0: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
e900: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
e910: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
e920: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
e930: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
e940: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
e950: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
e960: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
e970: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
e980: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
e990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e9a0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
e9b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
e9c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
e9d0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
e9e0: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
e9f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ea00: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
ea10: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
ea20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ea30: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
ea40: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
ea50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ea60: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
ea70: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
ea80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ea90: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
eaa0: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
eab0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
eac0: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
ead0: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
eae0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
eaf0: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
eb00: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
eb10: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
eb20: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
eb30: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
eb40: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
eb50: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
eb60: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53      22.#define S
eb70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
eb80: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_SET_HANDLE    
eb90: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51     23.#define SQ
eba0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
ebb0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
ebc0: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    24.#define SQL
ebd0: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
ebe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
ebf0: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   25.#define SQLI
ec00: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20  TE_FCNTL_RBU    
ec10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
ec20: 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  26.#define SQLIT
ec30: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
ec40: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32  TER            2
ec50: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
ec60: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
ec70: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38  OINTER        28
ec80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ec90: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
eca0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a  HANDLE       29.
ecb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ecc0: 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20  CNTL_PDB        
ecd0: 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 0a              30..
ece0: 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61  /* deprecated na
ecf0: 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mes */.#define S
ed00: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
ed10: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
ed20: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
ed30: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
ed40: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
ed50: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
ed60: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53    SQLITE_FCNTL_S
ed70: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
ed80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ed90: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
eda0: 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43         SQLITE_FC
edb0: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a  NTL_LAST_ERRNO..
edc0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
edd0: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
ede0: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
edf0: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
ee00: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
ee10: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
ee20: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
ee30: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
ee40: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
ee50: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
ee60: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
ee70: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
ee80: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
ee90: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
eea0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
eeb0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
eec0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
eed0: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
eee0: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
eef0: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
ef00: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
ef10: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
ef20: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
ef30: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
ef40: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
ef50: 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20  I3REF: Loadable 
ef60: 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a  Extension Thunk.
ef70: 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  **.** A pointer 
ef80: 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 71  to the opaque sq
ef90: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
efa0: 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20  es structure is 
efb0: 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65  passed as.** the
efc0: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
efd0: 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73   to entry points
efe0: 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78   of [loadable ex
eff0: 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73  tensions].  This
f000: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75  .** structure mu
f010: 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64 20  st be typedefed 
f020: 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b  in order to work
f030: 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72   around compiler
f040: 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20   warnings.** on 
f050: 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a  some platforms..
f060: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
f070: 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  t sqlite3_api_ro
f080: 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61  utines sqlite3_a
f090: 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a  pi_routines;../*
f0a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
f0b0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
f0c0: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
f0d0: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
f0e0: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
f0f0: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
f100: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
f110: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
f120: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
f130: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
f140: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
f150: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
f160: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
f170: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
f180: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
f190: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
f1a0: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
f1b0: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
f1c0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
f1d0: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
f1e0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
f1f0: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
f200: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
f210: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
f220: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
f230: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
f240: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
f250: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
f260: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
f270: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
f280: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
f290: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
f2a0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
f2b0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
f2c0: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
f2d0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
f2e0: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
f2f0: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
f300: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
f310: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
f320: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
f330: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
f340: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
f350: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
f360: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
f370: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
f380: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
f390: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
f3a0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
f3b0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
f3c0: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
f3d0: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
f3e0: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
f3f0: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
f400: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
f410: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
f420: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
f430: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
f440: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
f450: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
f460: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
f470: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
f480: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
f490: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
f4a0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
f4b0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
f4c0: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
f4d0: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
f4e0: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
f4f0: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
f500: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
f510: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
f520: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
f530: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
f540: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
f550: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
f560: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
f570: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
f580: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
f590: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
f5a0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
f5b0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
f5c0: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
f5d0: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
f5e0: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
f5f0: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
f600: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
f610: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
f620: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
f630: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
f640: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
f650: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
f660: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
f670: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
f680: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
f690: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
f6a0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
f6b0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
f6c0: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
f6d0: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
f6e0: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
f6f0: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
f700: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
f710: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
f720: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
f730: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
f740: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
f750: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
f760: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
f770: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
f780: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
f790: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
f7a0: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
f7b0: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
f7c0: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
f7d0: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
f7e0: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
f7f0: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
f800: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
f810: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
f820: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
f830: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
f840: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
f850: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
f860: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
f870: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
f880: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
f890: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
f8a0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
f8b0: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
f8c0: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
f8d0: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
f8e0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
f8f0: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
f900: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
f910: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
f920: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
f930: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
f940: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
f950: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
f960: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
f970: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
f980: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
f990: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
f9a0: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
f9b0: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
f9c0: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
f9d0: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
f9e0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
f9f0: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
fa00: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
fa10: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
fa20: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
fa30: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
fa40: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
fa50: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
fa60: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
fa70: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
fa80: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
fa90: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
faa0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
fab0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
fac0: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
fad0: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
fae0: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
faf0: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
fb00: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
fb10: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
fb20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
fb30: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
fb40: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
fb50: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
fb60: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
fb70: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
fb80: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
fb90: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
fba0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
fbb0: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
fbc0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
fbd0: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
fbe0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
fbf0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
fc00: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
fc10: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
fc20: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
fc30: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
fc40: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
fc50: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
fc60: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
fc70: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
fc80: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
fc90: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
fca0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
fcb0: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
fcc0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
fcd0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
fce0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
fcf0: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
fd00: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
fd10: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
fd20: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
fd30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
fd40: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
fd50: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
fd60: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
fd70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
fd80: 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
fd90: 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
fda0: 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
fdb0: 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
fdc0: 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
fdd0: 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
fde0: 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
fdf0: 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
fe00: 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
fe10: 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
fe20: 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
fe30: 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
fe40: 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
fe50: 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
fe60: 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
fe70: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
fe80: 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
fe90: 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
fea0: 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
feb0: 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
fec0: 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
fed0: 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
fee0: 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
fef0: 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
ff00: 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
ff10: 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
ff20: 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
ff30: 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
ff40: 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
ff50: 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
ff60: 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
ff70: 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
ff80: 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
ff90: 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
ffa0: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
ffb0: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
ffc0: 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
ffd0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
ffe0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
fff0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
10000 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
10010 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
10020 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
10030 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
10040 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
10050 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
10060 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
10070 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
10080 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
10090 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
100a0 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
100b0 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
100c0 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
100d0 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
100e0 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
100f0 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
10100 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
10110 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
10120 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
10130 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
10140 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
10150 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
10160 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
10170 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
10180 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
10190 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
101a0 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
101b0 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
101c0 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
101d0 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
101e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
101f0 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
10200 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
10210 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
10220 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
10230 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
10240 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
10250 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
10260 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
10270 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
10280 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
10290 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
102a0 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
102b0 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
102c0 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
102d0 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
102e0 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
102f0 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
10300 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
10310 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
10320 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
10330 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
10340 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
10350 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
10360 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
10370 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
10380 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
10390 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
103a0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
103b0 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
103c0 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
103d0 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
103e0 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
103f0 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
10400 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
10410 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
10420 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
10430 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
10440 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
10450 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
10460 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
10470 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
10480 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
10490 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
104a0 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
104b0 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
104c0 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
104d0 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
104e0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
104f0 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
10500 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
10510 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
10520 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
10530 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
10540 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
10550 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
10560 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
10570 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
10580 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
10590 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
105a0 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
105b0 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
105c0 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
105d0 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
105e0 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
105f0 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
10600 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
10610 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
10620 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
10630 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
10640 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
10650 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
10660 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
10670 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
10680 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
10690 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
106a0 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
106b0 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
106c0 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
106d0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
106e0 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
106f0 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
10700 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
10710 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
10720 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
10730 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
10740 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
10750 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
10760 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
10770 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
10780 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
10790 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
107a0 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
107b0 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
107c0 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
107d0 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
107e0 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
107f0 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
10800 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
10810 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
10820 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
10830 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
10840 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
10850 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
10860 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
10870 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
10880 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
10890 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
108a0 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
108b0 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
108c0 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
108d0 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
108e0 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
108f0 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
10900 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
10910 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
10920 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
10930 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
10940 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
10950 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
10960 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
10970 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
10980 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
10990 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
109a0 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
109b0 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
109c0 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
109d0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
109e0 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
109f0 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
10a00 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
10a10 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
10a20 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
10a30 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
10a40 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
10a50 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
10a60 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
10a70 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
10a80 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
10a90 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
10aa0 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
10ab0 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
10ac0 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
10ad0 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
10ae0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
10af0 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
10b00 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
10b10 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
10b20 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
10b30 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
10b40 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
10b50 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
10b60 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
10b70 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
10b80 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
10b90 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
10ba0 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
10bb0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
10bc0 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
10bd0 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
10be0 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
10bf0 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
10c00 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
10c10 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
10c20 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
10c30 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
10c40 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
10c50 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
10c60 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
10c70 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
10c80 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
10c90 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
10ca0 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
10cb0 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
10cc0 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
10cd0 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
10ce0 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
10cf0 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
10d00 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
10d10 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
10d20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
10d30 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
10d40 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
10d50 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
10d60 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
10d70 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
10d80 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
10d90 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
10da0 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
10db0 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
10dc0 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
10dd0 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
10de0 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
10df0 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
10e00 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
10e10 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
10e20 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
10e30 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
10e40 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
10e50 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
10e60 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
10e70 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
10e80 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
10e90 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
10ea0 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
10eb0 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
10ec0 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
10ed0 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
10ee0 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
10ef0 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
10f00 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
10f10 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
10f20 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
10f30 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
10f40 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
10f50 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
10f60 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
10f70 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
10f80 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
10f90 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
10fa0 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
10fb0 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
10fc0 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
10fd0 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
10fe0 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
10ff0 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
11000 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
11010 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
11020 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
11030 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
11040 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
11050 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
11060 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
11070 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
11080 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
11090 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
110a0 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
110b0 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
110c0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
110d0 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
110e0 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
110f0 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
11100 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
11110 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
11120 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
11130 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
11140 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
11150 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
11160 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
11170 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
11180 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
11190 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
111a0 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
111b0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
111c0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
111d0 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
111e0 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
111f0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
11200 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
11210 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
11220 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
11230 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
11240 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
11250 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
11260 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
11270 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
11280 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
11290 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
112a0 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
112b0 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
112c0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
112d0 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
112e0 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
112f0 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
11300 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
11310 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
11320 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
11330 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
11340 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
11350 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
11360 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
11370 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
11380 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
11390 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
113a0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
113b0 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
113c0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
113d0 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
113e0 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
113f0 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
11400 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
11410 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
11420 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
11430 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
11440 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
11450 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
11460 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
11470 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
11480 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
11490 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
114a0 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
114b0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
114c0 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
114d0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
114e0 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
114f0 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
11500 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
11510 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
11520 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
11530 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
11540 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
11550 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
11560 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
11570 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
11580 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
11590 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
115a0 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
115b0 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
115c0 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
115d0 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
115e0 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
115f0 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
11600 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
11610 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
11620 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
11630 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
11640 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
11650 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
11660 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
11670 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
11680 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
11690 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
116a0 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
116b0 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
116c0 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
116d0 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
116e0 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
116f0 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
11700 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
11710 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
11720 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
11730 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
11740 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
11750 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
11760 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
11770 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
11780 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
11790 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
117a0 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
117b0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
117c0 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
117d0 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
117e0 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
117f0 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
11800 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
11810 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
11820 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
11830 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
11840 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
11850 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
11860 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
11870 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
11880 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
11890 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
118a0 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
118b0 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
118c0 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
118d0 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
118e0 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
118f0 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
11900 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
11910 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
11920 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
11930 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
11940 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
11950 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
11960 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
11970 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
11980 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
11990 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
119a0 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
119b0 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
119c0 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
119d0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
119e0 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
119f0 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
11a00 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
11a10 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
11a20 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
11a30 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
11a40 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
11a50 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
11a60 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
11a70 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
11a80 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
11a90 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
11aa0 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
11ab0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
11ac0 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
11ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
11ae0 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
11af0 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
11b00 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
11b10 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
11b20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
11b30 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
11b40 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
11b50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11b60 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
11b70 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
11b80 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
11b90 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
11ba0 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
11bb0 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
11bc0 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
11bd0 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
11be0 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
11bf0 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
11c00 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
11c10 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
11c20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
11c30 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
11c40 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
11c50 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
11c60 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
11c70 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
11c80 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
11c90 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
11ca0 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
11cb0 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
11cc0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
11cd0 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
11ce0 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
11cf0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
11d00 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
11d10 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
11d20 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
11d30 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
11d40 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
11d50 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
11d60 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
11d70 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
11d80 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70  n on the corresp
11d90 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
11da0 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
11db0 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
11dc0 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
11dd0 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
11de0 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
11df0 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
11e00 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
11e10 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
11e20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
11e30 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
11e40 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
11e50 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
11e60 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
11e70 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
11e80 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
11e90 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
11ea0 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
11eb0 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
11ec0 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
11ed0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
11ee0 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
11ef0 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
11f00 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
11f10 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
11f20 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
11f30 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
11f40 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
11f50 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
11f60 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
11f70 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
11f80 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
11f90 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
11fa0 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
11fb0 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
11fc0 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
11fd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
11fe0 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
11ff0 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
12000 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
12010 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
12020 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
12030 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12040 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
12050 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
12060 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
12070 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
12080 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
12090 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
120a0 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
120b0 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
120c0 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
120d0 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
120e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
120f0 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
12100 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
12110 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
12120 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
12130 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
12140 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
12150 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
12160 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
12170 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
12180 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
12190 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
121a0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
121b0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
121c0 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
121d0 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
121e0 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
121f0 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
12200 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
12210 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
12220 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
12230 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
12240 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
12250 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
12260 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
12270 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
12280 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
12290 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
122a0 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
122b0 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
122c0 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
122d0 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
122e0 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
122f0 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
12300 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
12310 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
12320 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
12330 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
12340 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
12350 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
12360 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
12370 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
12380 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
12390 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
123a0 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
123b0 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
123c0 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
123d0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
123e0 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
123f0 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
12400 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
12410 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
12420 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
12430 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
12440 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
12450 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12460 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
12470 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
12480 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
12490 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
124a0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
124b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
124c0 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
124d0 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
124e0 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
124f0 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
12500 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
12510 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
12520 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
12530 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
12540 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
12550 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
12560 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
12570 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
12580 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
12590 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
125a0 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
125b0 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
125c0 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
125d0 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
125e0 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
125f0 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
12600 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
12610 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
12620 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
12630 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
12640 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
12650 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
12660 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
12670 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
12680 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
12690 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
126a0 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
126b0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
126c0 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
126d0 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
126e0 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
126f0 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
12700 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
12710 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
12720 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
12730 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12740 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
12750 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
12760 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
12770 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
12780 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
12790 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
127a0 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
127b0 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
127c0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
127d0 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
127e0 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
127f0 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
12800 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
12810 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
12820 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
12830 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
12840 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
12850 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
12860 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
12870 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
12880 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
12890 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
128a0 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
128b0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
128c0 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
128d0 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
128e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
128f0 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
12900 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
12910 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
12920 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
12930 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
12940 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
12950 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
12960 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
12970 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
12980 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
12990 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
129a0 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
129b0 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
129c0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
129d0 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
129e0 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
129f0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
12a00 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
12a10 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
12a20 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
12a30 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
12a40 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
12a50 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
12a60 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
12a70 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
12a80 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
12a90 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
12aa0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12ab0 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
12ac0 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
12ad0 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
12ae0 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
12af0 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
12b00 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
12b10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
12b20 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
12b30 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
12b40 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
12b50 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
12b60 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
12b70 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
12b80 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
12b90 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
12ba0 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
12bb0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
12bc0 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
12bd0 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
12be0 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
12bf0 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
12c00 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
12c10 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
12c20 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
12c30 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
12c40 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
12c50 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
12c60 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
12c70 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
12c80 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
12c90 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
12ca0 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
12cb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12cc0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
12cd0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
12ce0 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
12cf0 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
12d00 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
12d10 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
12d20 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
12d30 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
12d40 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
12d50 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
12d60 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
12d70 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
12d80 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
12d90 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
12da0 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
12db0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
12dc0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12dd0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
12de0 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
12df0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
12e00 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
12e10 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
12e20 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
12e30 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
12e40 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
12e50 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
12e60 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
12e70 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
12e80 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
12e90 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
12ea0 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
12eb0 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
12ec0 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
12ed0 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
12ee0 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
12ef0 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
12f00 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
12f10 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
12f20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
12f30 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12f40 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
12f50 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
12f60 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
12f70 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
12f80 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
12f90 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
12fa0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
12fb0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
12fc0 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
12fd0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
12fe0 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
12ff0 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
13000 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
13010 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ilure..*/.SQLITE
13020 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
13030 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
13040 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
13050 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
13060 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  wn(void);.SQLITE
13070 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
13080 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
13090 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
130a0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
130b0 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
130c0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
130d0 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
130e0 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rary.**.** The s
130f0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
13100 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
13110 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
13120 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
13130 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
13140 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
13150 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
13160 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
13170 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
13180 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
13190 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
131a0 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
131b0 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
131c0 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
131d0 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
131e0 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
131f0 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
13200 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
13210 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
13220 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
13230 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
13240 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74  .** <b>The sqlit
13250 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
13260 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
13270 65 61 64 73 61 66 65 2e 20 54 68 65 20 61 70 70  eadsafe. The app
13280 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
13290 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   ensure that no 
132a0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
132b0 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
132c0 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
132d0 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
132e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
132f0 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a  s running.</b>.*
13300 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
13310 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
13320 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ace.** may only 
13330 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72  be invoked prior
13340 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74   to library init
13350 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67  ialization using
13360 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  .** [sqlite3_ini
13370 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  tialize()] or af
13380 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20  ter shutdown by 
13390 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
133a0 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  n()]..** ^If sql
133b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
133c0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
133d0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
133e0 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a  e()] and before.
133f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
13400 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20  down()] then it 
13410 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
13420 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f  TE_MISUSE..** No
13430 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
13440 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t ^sqlite3_confi
13450 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  g() can be calle
13460 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
13470 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
13480 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61  on of an applica
13490 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71  tion-defined [sq
134a0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d  lite3_os_init()]
134b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
134c0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  t argument to sq
134d0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
134e0 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
134f0 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
13500 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
13510 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
13520 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
13530 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
13540 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
13550 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
13560 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
13570 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61  n the [configura
13580 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20  tion option].** 
13590 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
135a0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  ument..**.** ^Wh
135b0 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
135c0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
135d0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
135e0 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  () returns [SQLI
135f0 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74  TE_OK]..** ^If t
13600 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b  he option is unk
13610 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69  nown or SQLite i
13620 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20  s unable to set 
13630 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68  the option.** th
13640 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
13650 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
13660 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ro [error code].
13670 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
13680 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
13690 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
136a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
136b0 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
136c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
136d0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
136e0 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
136f0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
13700 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
13710 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72  to make configur
13720 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
13730 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20   to a [database 
13740 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
13750 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  e interface is s
13760 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71  imilar to.** [sq
13770 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13780 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20  except that the 
13790 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f  changes apply to
137a0 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61   a single.** [da
137b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
137c0 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e  n] (specified in
137d0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
137e0 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent)..**.** The 
137f0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
13800 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
13810 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69  nfig(D,V,...)  i
13820 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
13830 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
13840 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  IDE | configurat
13850 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69  ion verb] - an i
13860 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20  nteger code .** 
13870 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77  that indicates w
13880 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68  hat aspect of th
13890 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
138a0 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
138b0 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
138c0 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
138d0 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64  ents vary depend
138e0 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69  ing on the confi
138f0 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a  guration verb..*
13900 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  *.** ^Calls to s
13910 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
13920 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
13930 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  _OK if and only 
13940 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69  if.** the call i
13950 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63  s considered suc
13960 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  cessful..*/.SQLI
13970 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
13980 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
13990 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
139a0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
139b0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
139c0 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
139d0 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
139e0 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
139f0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
13a00 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
13a10 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
13a20 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
13a30 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
13a40 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
13a50 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
13a60 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
13a70 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
13a80 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
13a90 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
13aa0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
13ab0 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
13ac0 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
13ad0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
13ae0 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
13af0 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
13b00 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13b10 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
13b20 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
13b30 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
13b40 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
13b50 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
13b60 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
13b70 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
13b80 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
13b90 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
13ba0 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
13bb0 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
13bc0 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
13bd0 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
13be0 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
13bf0 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
13c00 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
13c10 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
13c20 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
13c30 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
13c40 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
13c50 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
13c60 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
13c70 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
13c80 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
13c90 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
13ca0 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
13cb0 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
13cc0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
13cd0 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
13ce0 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
13cf0 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
13d00 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
13d10 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
13d20 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
13d30 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13d40 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
13d50 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
13d60 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
13d70 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
13d80 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
13d90 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
13da0 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
13db0 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
13dc0 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
13dd0 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
13de0 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
13df0 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
13e00 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
13e10 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
13e20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
13e30 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
13e40 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61  he xMalloc, xRea
13e50 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20  lloc, and xFree 
13e60 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
13e70 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
13e80 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
13e90 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
13ea0 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
13eb0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
13ec0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  ry..** ^SQLite g
13ed0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
13ee0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
13ef0 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
13f00 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
13f10 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
13f20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
13f30 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20  xRoundup..**.** 
13f40 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
13f50 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
13f60 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
13f70 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
13f80 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
13f90 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
13fa0 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
13fb0 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
13fc0 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
13fd0 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
13fe0 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
13ff0 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
14000 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
14010 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
14020 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
14030 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
14040 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
14050 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
14060 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
14070 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
14080 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
14090 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
140a0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
140b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
140c0 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
140d0 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
140e0 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
140f0 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
14100 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
14110 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
14120 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
14130 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
14140 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
14150 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
14160 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14170 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
14180 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
14190 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
141a0 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
141b0 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
141c0 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
141d0 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
141e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
141f0 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
14200 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
14210 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
14220 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
14230 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a   For example,.**
14240 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
14250 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
14260 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
14270 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
14280 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
14290 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
142a0 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
142b0 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
142c0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
142d0 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
142e0 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
142f0 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
14300 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
14310 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
14320 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
14330 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
14340 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
14350 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
14360 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
14370 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
14380 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
14390 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
143a0 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
143b0 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
143c0 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
143d0 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
143e0 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
143f0 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
14400 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
14410 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
14420 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
14430 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
14440 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
14450 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
14460 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
14470 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
14480 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
14490 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
144a0 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
144b0 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
144c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
144d0 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
144e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
144f0 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
14500 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
14510 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
14520 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
14530 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
14540 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
14550 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
14560 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
14570 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
14580 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
14590 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
145a0 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
145b0 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
145c0 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
145d0 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
145e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
145f0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
14600 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
14610 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
14620 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
14630 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
14640 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
14650 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
14660 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
14670 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14680 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
14690 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
146a0 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
146b0 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
146c0 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
146d0 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
146e0 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
146f0 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
14700 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
14710 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
14720 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
14730 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
14740 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
14750 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
14760 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
14770 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
14780 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
14790 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
147a0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
147b0 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
147c0 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
147d0 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
147e0 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
147f0 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
14800 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
14810 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
14820 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
14830 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
14840 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
14850 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
14860 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
14870 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
14880 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
14890 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
148a0 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
148b0 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
148c0 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
148d0 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
148e0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
148f0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
14900 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
14910 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
14920 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
14930 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
14940 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
14950 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14960 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
14970 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
14980 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14990 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
149a0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
149b0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
149c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
149d0 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
149e0 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
149f0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
14a00 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
14a10 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14a20 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
14a30 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
14a40 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
14a50 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
14a60 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
14a70 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14a80 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
14a90 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
14aa0 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
14ab0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
14ac0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
14ad0 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
14ae0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
14af0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
14b00 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
14b10 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14b20 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
14b30 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
14b40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14b50 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
14b60 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14b70 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
14b80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
14b90 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
14ba0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
14bb0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
14bc0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
14bd0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
14be0 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
14bf0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
14c00 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
14c10 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
14c20 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
14c30 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
14c40 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
14c50 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
14c60 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
14c70 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14c80 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
14c90 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
14ca0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
14cb0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
14cc0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
14cd0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
14ce0 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
14cf0 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
14d00 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
14d10 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
14d20 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
14d30 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
14d40 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
14d50 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
14d60 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
14d70 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
14d80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
14d90 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
14da0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14db0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
14dc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14dd0 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
14de0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14df0 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
14e00 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
14e10 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
14e20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
14e30 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
14e40 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
14e50 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
14e60 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
14e70 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
14e80 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
14e90 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
14ea0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
14eb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
14ec0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
14ed0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
14ee0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
14ef0 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
14f00 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
14f10 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14f20 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
14f30 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
14f40 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
14f50 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
14f60 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
14f70 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
14f80 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
14f90 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
14fa0 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
14fb0 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
14fc0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
14fd0 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
14fe0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14ff0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
15000 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
15010 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
15020 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
15030 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
15040 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
15050 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
15060 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
15070 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
15080 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
15090 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
150a0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
150b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
150c0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
150d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
150e0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
150f0 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
15100 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
15110 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15120 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
15130 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
15140 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
15150 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
15160 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
15170 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
15180 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
15190 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
151a0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
151b0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
151c0 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
151d0 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
151e0 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
151f0 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
15200 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
15210 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
15220 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
15230 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15240 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
15250 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
15260 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
15270 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
15280 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
15290 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
152a0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
152b0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
152c0 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
152d0 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
152e0 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
152f0 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
15300 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
15310 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
15320 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
15330 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
15340 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
15350 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
15360 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15370 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
15380 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
15390 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
153a0 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
153b0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
153c0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
153d0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
153e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
153f0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
15400 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
15410 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15420 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
15430 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
15440 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
15450 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
15460 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
15470 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
15480 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
15490 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
154a0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
154b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
154c0 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
154d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
154e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
154f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
15500 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15510 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
15520 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
15530 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
15540 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
15550 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
15560 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
15570 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
15580 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
15590 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
155a0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
155b0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
155c0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
155d0 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
155e0 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
155f0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
15600 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
15610 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
15620 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
15630 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
15640 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
15650 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
15660 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
15670 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
15680 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
15690 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
156a0 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
156b0 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
156c0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
156d0 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
156e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
156f0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
15700 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15710 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
15720 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
15730 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15740 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
15750 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15760 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
15770 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
15780 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
15790 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
157a0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
157b0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
157c0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
157d0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
157e0 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
157f0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
15800 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15810 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
15820 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
15830 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
15840 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
15850 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
15860 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
15870 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
15880 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
15890 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
158a0 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
158b0 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
158c0 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
158d0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
158e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
158f0 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
15900 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
15910 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
15920 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
15930 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
15940 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
15950 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
15960 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74  type int,.** int
15970 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
15980 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
15990 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
159a0 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
159b0 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  of.** memory all
159c0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
159d0 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
159e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
159f0 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64  tistics are.** d
15a00 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c  isabled, the fol
15a10 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
15a20 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
15a30 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
15a40 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
15a50 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
15a60 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
15a70 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
15a80 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
15a90 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
15aa0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
15ab0 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
15ac0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
15ad0 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20  tatus64()].**   
15ae0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
15af0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
15b00 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
15b10 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
15b20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
15b30 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
15b40 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
15b50 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
15b60 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
15b70 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
15b80 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
15b90 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
15ba0 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
15bb0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15bc0 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c  NFIG_SCRATCH]] <
15bd0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15be0 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
15bf0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
15c00 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
15c10 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
15c20 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
15c30 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  y buffer.** that
15c40 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
15c50 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  for scratch memo
15c60 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65  ry.  ^(There are
15c70 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
15c80 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  .** to SQLITE_CO
15c90 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41  NFIG_SCRATCH:  A
15ca0 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
15cb0 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
15cc0 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
15cd0 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
15ce0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
15cf0 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
15d00 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
15d10 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
15d20 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
15d30 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
15d40 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
15d50 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
15d60 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  )^.** The first 
15d70 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
15d80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
15d90 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
15da0 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
15db0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
15dc0 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
15dd0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20  SQLite will not 
15de0 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  use more than on
15df0 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  e scratch buffer
15e00 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a  s per thread..**
15e10 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
15e20 76 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63  ver request a sc
15e30 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
15e40 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
15e50 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61  .** times the da
15e60 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
15e70 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
15e80 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
15e90 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
15ea0 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
15eb0 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
15ec0 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
15ed0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
15ee0 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
15ef0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
15f00 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
15f10 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
15f20 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e  ded.<p>.** ^When
15f30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
15f40 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d   provides any am
15f50 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20  ount of scratch 
15f60 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20  memory using.** 
15f70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
15f80 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76  RATCH, SQLite av
15f90 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79  oids unnecessary
15fa0 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74   large.** [sqlit
15fb0 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61  e3_malloc|heap a
15fc0 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20  llocations]..** 
15fd0 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52  This can help [R
15fe0 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76  obson proof|prev
15ff0 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ent memory alloc
16000 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20  ation failures] 
16010 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66  due to heap.** f
16020 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20  ragmentation in 
16030 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64  low-memory embed
16040 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20  ded systems..** 
16050 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16060 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
16070 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
16080 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
16090 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
160a0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
160b0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70  FIG_PAGECACHE op
160c0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
160d0 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20   memory pool.** 
160e0 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
160f0 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61  use for the data
16100 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
16110 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
16120 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
16130 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
16140 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
16150 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
16160 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61   a no-op if an a
16170 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
16180 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
16190 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
161a0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
161b0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
161c0 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e  G_PCACHE2]..** ^
161d0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
161e0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
161f0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
16200 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20  ACHE: A pointer 
16210 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69  to.** 8-byte ali
16220 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65  gned memory (pMe
16230 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  m), the size of 
16240 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20  each page cache 
16250 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  line (sz),.** an
16260 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
16270 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e  cache lines (N).
16280 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
16290 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
162a0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
162b0 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
162c0 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
162d0 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
162e0 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c  12 and 65536) pl
162f0 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79  us some extra by
16300 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tes for each.** 
16310 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
16320 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
16330 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20  ra bytes needed 
16340 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64  by the page head
16350 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  er.** can be det
16360 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53  ermined using [S
16370 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16380 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e  CHE_HDRSZ]..** ^
16390 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
163a0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
163b0 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
163c0 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61   for the sz para
163d0 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67  meter to be larg
163e0 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72  er than necessar
163f0 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20  y.  The pMem.** 
16400 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
16410 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
16420 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e  ointer or a poin
16430 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
16440 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  .** aligned bloc
16450 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61  k of memory of a
16460 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
16470 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a  es, otherwise.**
16480 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
16490 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
164a0 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d  d..** ^When pMem
164b0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
164c0 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65  Lite will strive
164d0 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f   to use the memo
164e0 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74  ry provided.** t
164f0 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63  o satisfy page c
16500 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c  ache needs, fall
16510 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c  ing back to [sql
16520 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
16530 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68  f.** a page cach
16540 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72  e line is larger
16550 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f   than sz bytes o
16560 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20  r if all of the 
16570 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69  pMem buffer.** i
16580 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
16590 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c  ^If pMem is NULL
165a0 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65   and N is non-ze
165b0 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61  ro, then each da
165c0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
165d0 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69  n.** does an ini
165e0 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61  tial bulk alloca
165f0 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61  tion for page ca
16600 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72  che memory.** fr
16610 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
16620 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74  oc()] sufficient
16630 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e   for N cache lin
16640 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  es if N is posit
16650 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30  ive or.** of -10
16660 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20  24*N bytes if N 
16670 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e  is negative, . ^
16680 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
16690 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
166a0 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
166b0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
166c0 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74  ided by the init
166d0 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ial.** allocatio
166e0 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67  n, then SQLite g
166f0 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
16700 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61  malloc()] separa
16710 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a  tely for each.**
16720 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68   additional cach
16730 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  e line. </dd>.**
16740 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16750 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
16760 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
16770 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
16780 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16790 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70  G_HEAP option sp
167a0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
167b0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a   memory buffer .
167c0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  ** that SQLite w
167d0 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20  ill use for all 
167e0 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
167f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16800 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64   needs.** beyond
16810 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20   those provided 
16820 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
16830 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
16840 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  nd.** [SQLITE_CO
16850 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
16860 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
16870 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
16880 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
16890 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
168a0 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
168b0 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  th either [SQLIT
168c0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
168d0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ] or [SQLITE_ENA
168e0 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64  BLE_MEMSYS5] and
168f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
16900 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e  ITE_ERROR] if in
16910 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e  voked otherwise.
16920 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
16930 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
16940 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
16950 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79  HEAP:.** An 8-by
16960 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
16970 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
16980 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
16990 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
169a0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
169b0 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
169c0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
169d0 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
169e0 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
169f0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
16a00 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
16a10 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
16a20 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
16a30 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
16a40 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
16a50 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
16a60 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
16a70 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
16a80 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
16a90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
16aa0 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
16ab0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
16ac0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
16ad0 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
16ae0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
16af0 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
16b00 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
16b10 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
16b20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
16b30 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
16b40 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
16b50 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
16b60 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
16b70 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
16b80 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
16b90 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
16ba0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
16bb0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
16bc0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
16bd0 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65  on size is cappe
16be0 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73  d at 2**12. Reas
16bf0 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a  onable values.**
16c00 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d   for the minimum
16c10 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
16c20 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67   are 2**5 throug
16c30 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a  h 2**8.</dd>.**.
16c40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16c50 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  IG_MUTEX]] <dt>S
16c60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
16c70 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
16c80 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
16c90 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e  FIG_MUTEX option
16ca0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
16cb0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
16cc0 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
16cd0 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
16ce0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
16cf0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
16d00 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
16d10 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
16d20 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  s alternative lo
16d30 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
16d40 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
16d50 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68  d.** in place th
16d60 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
16d70 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
16d80 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
16d90 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  akes a copy of.*
16da0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
16db0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
16dc0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
16dd0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
16de0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
16df0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
16e00 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
16e10 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
16e20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
16e30 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
16e40 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
16e50 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
16e60 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
16e70 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
16e80 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
16e90 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
16ea0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
16eb0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
16ec0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
16ed0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
16ee0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
16ef0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16f00 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
16f10 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
16f20 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
16f30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
16f40 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
16f50 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16f60 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
16f70 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
16f80 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f  ONFIG_GETMUTEX o
16f90 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
16fa0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
16fb0 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
16fc0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
16fd0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
16fe0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
16ff0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
17000 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
17010 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
17020 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
17030 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
17040 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
17050 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
17060 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
17070 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
17080 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
17090 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
170a0 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
170b0 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
170c0 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
170d0 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
170e0 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
170f0 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
17100 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
17110 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
17120 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
17130 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
17140 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
17150 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
17160 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
17170 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
17180 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
17190 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
171a0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
171b0 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
171c0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
171d0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
171e0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
171f0 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
17200 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17210 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
17220 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
17230 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
17240 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
17250 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
17260 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
17270 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
17280 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
17290 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70  FIG_LOOKASIDE op
172a0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
172b0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
172c0 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64  termine.** the d
172d0 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c  efault size of l
172e0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
172f0 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73  on each [databas
17300 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
17310 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
17320 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
17330 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
17340 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
17350 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
17360 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
17370 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
17380 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
17390 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
173a0 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f  .)^  ^(SQLITE_CO
173b0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a  NFIG_LOOKASIDE.*
173c0 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65  * sets the <i>de
173d0 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
173e0 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
173f0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
17400 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74  OOKASIDE].** opt
17410 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ion to [sqlite3_
17420 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
17430 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
17440 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
17450 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
17460 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
17470 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
17480 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
17490 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
174a0 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
174b0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f  CONFIG_PCACHE2</
174c0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
174d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
174e0 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
174f0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
17500 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
17510 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
17520 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
17530 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
17540 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
17550 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ct specifies.** 
17560 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  the interface to
17570 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
17580 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
17590 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74  ion.)^.** ^SQLit
175a0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
175b0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  f the [sqlite3_p
175c0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
175d0 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  object.</dd>.**.
175e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
175f0 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
17600 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17610 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
17620 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
17630 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
17640 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  TPCACHE2 option 
17650 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
17660 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
17670 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17680 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
17690 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
176a0 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
176b0 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63  pies of.** the c
176c0 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68  urrent page cach
176d0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
176e0 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
176f0 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
17700 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
17710 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
17720 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
17730 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
17740 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
17750 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17760 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
17770 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
17780 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
17790 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
177a0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
177b0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
177c0 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
177d0 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
177e0 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
177f0 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
17800 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
17810 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
17820 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
17830 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
17840 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
17850 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
17860 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
17870 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
17880 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
17890 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
178a0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
178b0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
178c0 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
178d0 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
178e0 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
178f0 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
17900 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
17910 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
17920 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
17930 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
17940 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
17950 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
17960 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
17970 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
17980 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
17990 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
179a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
179b0 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
179c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
179d0 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
179e0 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
179f0 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
17a00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
17a10 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
17a20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
17a30 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
17a40 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
17a50 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
17a60 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
17a70 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
17a80 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
17a90 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
17aa0 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
17ab0 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
17ac0 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
17ad0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
17ae0 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
17af0 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
17b00 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
17b10 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
17b20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
17b30 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
17b40 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
17b50 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
17b60 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
17b70 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
17b80 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
17b90 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
17ba0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
17bb0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
17bc0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
17bd0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
17be0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
17bf0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
17c00 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
17c10 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
17c20 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74  FIG_URI option t
17c30 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
17c40 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
17c50 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65  nt..** If non-ze
17c60 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
17c70 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
17c80 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
17c90 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
17ca0 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49  ero,.** then URI
17cb0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
17cc0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29  bally disabled.)
17cd0 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69  ^ ^If URI handli
17ce0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
17cf0 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66  * enabled, all f
17d00 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20  ilenames passed 
17d10 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
17d20 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
17d30 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  en_v2()],.** [sq
17d40 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
17d50 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  or.** specified 
17d60 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41  as part of [ATTA
17d70 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65  CH] commands are
17d80 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
17d90 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73  URIs, regardless
17da0 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f  .** of whether o
17db0 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
17dc0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
17dd0 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
17de0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
17df0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
17e00 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f  d. ^If it is glo
17e10 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
17e20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
17e30 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
17e40 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
17e50 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
17e60 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
17e70 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
17e80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
17e90 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66  opened. ^(By def
17ea0 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
17eb0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
17ec0 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
17ed0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
17ee0 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
17ef0 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
17f00 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
17f10 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
17f20 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  fined.)^.**.** [
17f30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
17f40 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
17f50 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
17f60 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
17f70 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
17f80 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
17f90 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
17fa0 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20  DEX_SCAN option 
17fb0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69  takes a single i
17fc0 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65  nteger.** argume
17fd0 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
17fe0 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
17ff0 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f  lean in order to
18000 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
18010 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  le.** the use of
18020 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
18030 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
18040 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75   scans in the qu
18050 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a  ery optimizer..*
18060 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
18070 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d  etting is determ
18080 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  ined.** by the [
18090 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56  SQLITE_ALLOW_COV
180a0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
180b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
180c0 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e  ption, or is "on
180d0 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d  ".** if that com
180e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
180f0 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20   is omitted..** 
18100 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64  The ability to d
18110 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
18120 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
18130 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
18140 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65  e scans.** is be
18150 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72  cause some incor
18160 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67  rectly coded leg
18170 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  acy applications
18180 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69   might malfuncti
18190 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f  on.** when the o
181a0 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65  ptimization is e
181b0 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69  nabled.  Providi
181c0 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  ng the ability t
181d0 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65  o.** disable the
181e0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c   optimization al
181f0 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20  lows the older, 
18200 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f  buggy applicatio
18210 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a  n code to work.*
18220 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65  * without change
18230 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72   even with newer
18240 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
18250 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ite..**.** [[SQL
18260 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
18270 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  E]] [[SQLITE_CON
18280 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a  FIG_GETPCACHE]].
18290 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
182a0 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20  NFIG_PCACHE and 
182b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
182c0 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20  TPCACHE.** <dd> 
182d0 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72  These options ar
182e0 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73  e obsolete and s
182f0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
18300 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a  d by new code..*
18310 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69  * They are retai
18320 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
18330 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
18340 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f  but are now no-o
18350 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ps..** </dd>.**.
18360 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
18370 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c  IG_SQLLOG]].** <
18380 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
18390 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54  _SQLLOG.** <dd>T
183a0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
183b0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
183c0 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  sqlite is compil
183d0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
183e0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51  SQLITE_ENABLE_SQ
183f0 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOG] pre-proces
18400 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  sor macro define
18410 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  d. The first arg
18420 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  ument should.** 
18430 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
18440 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
18450 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  pe void(*)(void*
18460 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20  ,sqlite3*,const 
18470 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20  char*, int)..** 
18480 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c  The second shoul
18490 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f  d be of type (vo
184a0 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61  id*). The callba
184b0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  ck is invoked by
184c0 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20   the library.** 
184d0 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74  in three separat
184e0 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
184f0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
18500 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
18510 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
18520 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74   parameter. If t
18530 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
18540 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74  ter is 0, then t
18550 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18560 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64  ection.** passed
18570 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
18580 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74  rgument has just
18590 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68   been opened. Th
185a0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
185b0 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  .** points to a 
185c0 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e  buffer containin
185d0 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  g the name of th
185e0 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
185f0 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20  file. If the.** 
18600 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
18610 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20   is 1, then the 
18620 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
18630 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72  at the third par
18640 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73  ameter.** points
18650 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65   to has just bee
18660 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20  n executed. Or, 
18670 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  if the fourth pa
18680 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68  rameter is 2, th
18690 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63  en.** the connec
186a0 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65  tion being passe
186b0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
186c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69  parameter is bei
186d0 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a  ng closed. The.*
186e0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
186f0 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c  r is passed NULL
18700 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20   In this case.  
18710 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73  An example of us
18720 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66  ing this.** conf
18730 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
18740 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20   can be seen in 
18750 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67  the "test_sqllog
18760 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20  .c" source file 
18770 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69  in.** the canoni
18780 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63  cal SQLite sourc
18790 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  e tree.</dd>.**.
187a0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
187b0 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  IG_MMAP_SIZE]].*
187c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
187d0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a  FIG_MMAP_SIZE.**
187e0 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e   <dd>^SQLITE_CON
187f0 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61  FIG_MMAP_SIZE ta
18800 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69  kes two 64-bit i
18810 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f  nteger (sqlite3_
18820 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a  int64) values.**
18830 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65   that are the de
18840 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20  fault mmap size 
18850 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75  limit (the defau
18860 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a  lt setting for.*
18870 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  * [PRAGMA mmap_s
18880 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61  ize]) and the ma
18890 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
188a0 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a  ap size limit..*
188b0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
188c0 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76  etting can be ov
188d0 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68  erridden by each
188e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
188f0 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69  tion using.** ei
18900 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41  ther the [PRAGMA
18910 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d   mmap_size] comm
18920 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67  and, or by using
18930 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
18940 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
18950 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20   file control.  
18960 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  ^(The maximum al
18970 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a  lowed mmap size.
18980 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e  ** will be silen
18990 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66  tly truncated if
189a0 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68   necessary so th
189b0 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65  at it does not e
189c0 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  xceed the.** com
189d0 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75  pile-time maximu
189e0 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20  m mmap size set 
189f0 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
18a00 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d  E_MAX_MMAP_SIZE]
18a10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
18a20 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65  tion.)^.** ^If e
18a30 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74  ither argument t
18a40 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  o this option is
18a50 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
18a60 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73  that argument is
18a70 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69  .** changed to i
18a80 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ts compile-time 
18a90 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b  default..**.** [
18aa0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  [SQLITE_CONFIG_W
18ab0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a  IN32_HEAPSIZE]].
18ac0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
18ad0 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
18ae0 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  IZE.** <dd>^The 
18af0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
18b00 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74  N32_HEAPSIZE opt
18b10 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
18b20 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
18b30 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66  is.** compiled f
18b40 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20  or Windows with 
18b50 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33  the [SQLITE_WIN3
18b60 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72  2_MALLOC] pre-pr
18b70 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a  ocessor macro.**
18b80 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54   defined. ^SQLIT
18b90 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
18ba0 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
18bb0 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
18bc0 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
18bd0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
18be0 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
18bf0 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20   of the created 
18c00 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  heap..**.** [[SQ
18c10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
18c20 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64  HE_HDRSZ]].** <d
18c30 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
18c40 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20  PCACHE_HDRSZ.** 
18c50 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
18c60 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
18c70 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  RSZ option takes
18c80 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
18c90 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
18ca0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
18cb0 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74  integer and writ
18cc0 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  es into that int
18cd0 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20  eger the number 
18ce0 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65  of extra.** byte
18cf0 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69  s per page requi
18d00 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67  red for each pag
18d10 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e in [SQLITE_CON
18d20 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
18d30 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ** The amount of
18d40 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71   extra space req
18d50 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65  uired can change
18d60 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
18d70 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74  e compiler,.** t
18d80 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20  arget platform, 
18d90 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
18da0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  on..**.** [[SQLI
18db0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d  TE_CONFIG_PMASZ]
18dc0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
18dd0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20  CONFIG_PMASZ.** 
18de0 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
18df0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74  CONFIG_PMASZ opt
18e00 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
18e10 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
18e20 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69  ch.** is an unsi
18e30 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
18e40 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d   sets the "Minim
18e50 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72  um PMA Size" for
18e60 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64   the multithread
18e70 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20  ed.** sorter to 
18e80 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54  that integer.  T
18e90 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d  he default minim
18ea0 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73  um PMA Size is s
18eb0 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
18ec0 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53  LITE_SORTER_PMAS
18ed0 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  Z] compile-time 
18ee0 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72  option.  New thr
18ef0 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65  eads are launche
18f00 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74  d.** to help wit
18f10 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e  h sort operation
18f20 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65  s when multithre
18f30 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20  aded sorting.** 
18f40 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e  is enabled (usin
18f50 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68  g the [PRAGMA th
18f60 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20  reads] command) 
18f70 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  and the amount o
18f80 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20  f content.** to 
18f90 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64  be sorted exceed
18fa0 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20  s the page size 
18fb0 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75  times the minimu
18fc0 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41  m of the.** [PRA
18fd0 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20  GMA cache_size] 
18fe0 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73  setting and this
18ff0 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   value..**.** [[
19000 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
19010 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a  MTJRNL_SPILL]].*
19020 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
19030 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
19040 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  LL.** <dd>^The S
19050 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
19060 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69  TJRNL_SPILL opti
19070 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
19080 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
19090 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65  h.** becomes the
190a0 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [statement jour
190b0 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69  nal] spill-to-di
190c0 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a  sk threshold.  .
190d0 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f  ** [Statement jo
190e0 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64  urnals] are held
190f0 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c   in memory until
19100 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20   their size (in 
19110 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64  bytes).** exceed
19120 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64  s this threshold
19130 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74  , at which point
19140 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65   they are writte
19150 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72  n to disk..** Or
19160 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c   if the threshol
19170 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65  d is -1, stateme
19180 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20  nt journals are 
19190 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65  always held.** e
191a0 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65  xclusively in me
191b0 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d  mory..** Since m
191c0 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f  any statement jo
191d0 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63  urnals never bec
191e0 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69  ome large, setti
191f0 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20  ng the spill.** 
19200 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76  threshold to a v
19210 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b  alue such as 64K
19220 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72  iB can greatly r
19230 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74  educe the amount
19240 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69   of.** I/O requi
19250 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73  red to support s
19260 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63  tatement rollbac
19270 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  k..** The defaul
19280 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73  t value for this
19290 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74   setting is cont
192a0 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  rolled by the.**
192b0 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e   [SQLITE_STMTJRN
192c0 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65  L_SPILL] compile
192d0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
192e0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
192f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19300 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
19310 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
19320 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
19330 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
19340 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
19350 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
19360 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
19370 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
19380 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19390 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
193a0 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
193b0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
193c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
193d0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
193e0 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
193f0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
19400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19410 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
19420 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
19430 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
19440 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19450 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
19460 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
19470 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
19480 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
19490 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
194a0 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
194b0 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
194c0 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
194d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
194e0 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
194f0 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
19500 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19510 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
19520 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
19530 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
19540 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
19550 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
19560 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
19570 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
19580 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
19590 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
195a0 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
195b0 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
195c0 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
195d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
195e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
195f0 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
19600 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19610 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
19620 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
19630 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19640 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
19650 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
19660 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
19670 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
19680 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
19690 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
196a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
196b0 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
196c0 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
196d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
196e0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
196f0 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
19700 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
19710 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
19720 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
19730 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
19740 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
19750 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
19760 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
19770 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
19780 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69  EX_SCAN 20  /* i
19790 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
197a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
197b0 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20  OG       21  /* 
197c0 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a  xSqllog, void* *
197d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
197e0 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
197f0 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69  E    22  /* sqli
19800 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74  te3_int64, sqlit
19810 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66  e3_int64 */.#def
19820 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
19830 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
19840 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74        23  /* int
19850 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e   nByte */.#defin
19860 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19870 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20  PCACHE_HDRSZ    
19880 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a      24  /* int *
19890 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  psz */.#define S
198a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
198b0 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  SZ              
198c0 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64   25  /* unsigned
198d0 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64   int szPma */.#d
198e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
198f0 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
19900 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69  LL      26  /* i
19910 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a  nt nByte */../*.
19920 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
19930 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
19940 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
19950 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
19960 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
19970 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
19980 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
19990 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
199a0 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
199b0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
199c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
199d0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
199e0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
199f0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
19a00 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
19a10 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
19a20 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
19a30 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
19a40 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
19a50 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
19a60 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
19a70 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
19a80 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
19a90 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
19aa0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
19ab0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
19ac0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
19ad0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
19ae0 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
19af0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
19b00 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
19b10 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
19b20 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
19b30 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
19b40 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
19b50 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
19b60 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
19b70 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
19b80 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
19b90 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
19ba0 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
19bb0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
19bc0 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
19bd0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
19be0 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
19bf0 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
19c00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
19c10 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
19c20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
19c30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
19c40 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
19c50 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
19c60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
19c70 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
19c80 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
19c90 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
19ca0 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
19cb0 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
19cc0 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
19cd0 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
19ce0 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
19cf0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
19d00 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
19d10 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
19d20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
19d30 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
19d40 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
19d50 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
19d60 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
19d70 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
19d80 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
19d90 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
19da0 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
19db0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
19dc0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
19dd0 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
19de0 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
19df0 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
19e00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
19e10 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
19e20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
19e30 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
19e40 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
19e50 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
19e60 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
19e70 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
19e80 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
19e90 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
19ea0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
19eb0 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
19ec0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
19ed0 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
19ee0 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
19ef0 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
19f00 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
19f10 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d  e next smaller m
19f20 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e  ultiple of 8.  ^
19f30 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  (The lookaside m
19f40 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75  emory.** configu
19f50 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74  ration for a dat
19f60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19f70 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61   can only be cha
19f80 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a  nged when that.*
19f90 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
19fa0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73  not currently us
19fb0 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ing lookaside me
19fc0 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65  mory, or in othe
19fd0 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20  r words.** when 
19fe0 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c  the "current val
19ff0 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ue" returned by.
1a000 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73  ** [sqlite3_db_s
1a010 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45  tatus](D,[SQLITE
1a020 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
1a030 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e  E],...) is zero.
1a040 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
1a050 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
1a060 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63  okaside memory c
1a070 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65  onfiguration whe
1a080 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d  n lookaside.** m
1a090 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20  emory is in use 
1a0a0 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69  leaves the confi
1a0b0 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67  guration unchang
1a0c0 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a  ed and returns .
1a0d0 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1a0e0 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  .)^</dd>.**.** <
1a0f0 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
1a100 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f  IG_ENABLE_FKEY</
1a110 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
1a120 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
1a130 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
1a140 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63  sable the enforc
1a150 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72  ement of.** [for
1a160 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
1a170 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68  ints].  There sh
1a180 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
1a190 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
1a1a0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
1a1b0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
1a1c0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
1a1d0 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65   to disable FK e
1a1e0 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70  nforcement,.** p
1a1f0 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
1a200 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
1a210 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
1a220 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65  leave FK enforce
1a230 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ment.** unchange
1a240 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  d.  The second p
1a250 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
1a260 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
1a270 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
1a280 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
1a290 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
1a2a0 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72  whether FK enfor
1a2b0 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72  cement is off or
1a2c0 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67   on.** following
1a2d0 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
1a2e0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a2f0 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
1a300 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
1a310 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b  hich case the FK
1a320 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74   enforcement set
1a330 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
1a340 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
1a350 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1a360 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1a370 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a  E_TRIGGER</dt>.*
1a380 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
1a390 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
1a3a0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
1a3b0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
1a3c0 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a   | triggers]..**
1a3d0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
1a3e0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1a3f0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
1a400 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1a410 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
1a420 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
1a430 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a  able triggers,.*
1a440 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
1a450 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72  able triggers or
1a460 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
1a470 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
1a480 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
1a490 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a4a0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
1a4b0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
1a4c0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
1a4d0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
1a4e0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
1a4f0 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69   triggers are di
1a500 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
1a510 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
1a520 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
1a530 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1a540 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
1a550 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
1a560 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67  ch case the trig
1a570 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ger setting is n
1a580 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
1a590 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
1a5a0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
1a5b0 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f  G_ENABLE_FTS3_TO
1a5c0 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20  KENIZER</dt>.** 
1a5d0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
1a5e0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
1a5f0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
1a600 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a  he two-argument.
1a610 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ** version of th
1a620 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  e [fts3_tokenize
1a630 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68  r()] function wh
1a640 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74  ich is part of t
1a650 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c  he.** [FTS3] ful
1a660 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e  l-text search en
1a670 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a  gine extension..
1a680 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
1a690 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
1a6a0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
1a6b0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1a6c0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
1a6d0 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
1a6e0 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65  isable fts3_toke
1a6f0 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f  nizer() or.** po
1a700 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
1a710 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28   fts3_tokenizer(
1a720 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  ) or negative to
1a730 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
1a740 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  ng.** unchanged.
1a750 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
1a760 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
1a770 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
1a780 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
1a790 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
1a7a0 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
1a7b0 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b  whether fts3_tok
1a7c0 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  enizer is disabl
1a7d0 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
1a7e0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
1a7f0 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
1a800 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
1a810 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
1a820 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
1a830 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74  ase the new sett
1a840 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
1a850 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
1a860 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1a870 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1a880 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c  _LOAD_EXTENSION<
1a890 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
1a8a0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
1a8b0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
1a8c0 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69  isable the [sqli
1a8d0 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
1a8e0 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  on()].** interfa
1a8f0 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79  ce independently
1a900 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78   of the [load_ex
1a910 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66  tension()] SQL f
1a920 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
1a930 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
1a940 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
1a950 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72  ] API enables or
1a960 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74   disables both t
1a970 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c  he.** C-API [sql
1a980 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
1a990 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53  ion()] and the S
1a9a0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61  QL function [loa
1a9b0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a  d_extension()]..
1a9c0 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
1a9d0 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
1a9e0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
1a9f0 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61  When the first a
1aa00 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
1aa10 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20  interface is 1, 
1aa20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d  then only the C-
1aa30 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65  API is.** enable
1aa40 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  d and the SQL fu
1aa50 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64  nction remains d
1aa60 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65  isabled.  If the
1aa70 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1aa80 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72  to.** this inter
1aa90 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20  face is 0, then 
1aaa0 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61  both the C-API a
1aab0 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nd the SQL funct
1aac0 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64  ion are disabled
1aad0 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73  ..** If the firs
1aae0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31  t argument is -1
1aaf0 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65  , then no change
1ab00 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74  s are made to st
1ab10 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68  ate of either th
1ab20 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68  e.** C-API or th
1ab30 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a  e SQL function..
1ab40 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
1ab50 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
1ab60 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
1ab70 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
1ab80 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
1ab90 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
1aba0 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  hether [sqlite3_
1abb0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
1abc0 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ] interface.** i
1abd0 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  s disabled or en
1abe0 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20  abled following 
1abf0 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
1ac00 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1ac10 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c   may.** be a NUL
1ac20 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68  L pointer, in wh
1ac30 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77  ich case the new
1ac40 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
1ac50 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a  reported back..*
1ac60 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
1ac70 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
1ac80 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74  G_MAINDBNAME</dt
1ac90 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
1aca0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
1acb0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d  o change the nam
1acc0 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20  e of the "main" 
1acd0 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65  database.** sche
1ace0 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61  ma.  ^The sole a
1acf0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
1ad00 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61  nter to a consta
1ad10 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a  nt UTF8 string.*
1ad20 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63  * which will bec
1ad30 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65  ome the new sche
1ad40 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65  ma name in place
1ad50 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51   of "main".  ^SQ
1ad60 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  Lite.** does not
1ad70 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
1ad80 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68  the new main sch
1ad90 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c  ema name string,
1ada0 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   so the applicat
1adb0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75  ion.** must ensu
1adc0 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75  re that the argu
1add0 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f  ment passed into
1ade0 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f   this DBCONFIG o
1adf0 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67  ption is unchang
1ae00 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65  ed.** until afte
1ae10 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  r the database c
1ae20 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
1ae30 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
1ae40 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
1ae50 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f  NFIG_NO_CKPT_ON_
1ae60 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CLOSE</dt>.** <d
1ae70 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e  d> Usually, when
1ae80 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 77   a database in w
1ae90 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65  al mode is close
1aea0 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 72  d or detached fr
1aeb0 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73  om a .** databas
1aec0 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65  e handle, SQLite
1aed0 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 20   checks if this 
1aee0 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74  will mean that t
1aef0 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20  here are now no 
1af00 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  .** connections 
1af10 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61  at all to the da
1af20 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69  tabase. If so, i
1af30 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65  t performs a che
1af40 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72  ckpoint .** oper
1af50 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f  ation before clo
1af60 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74  sing the connect
1af70 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e  ion. This option
1af80 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a   may be used to.
1af90 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 73  ** override this
1afa0 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20   behaviour. The 
1afb0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1afc0 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f  passed to this o
1afd0 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61  peration.** is a
1afe0 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e 2d  n integer - non-
1aff0 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20  zero to disable 
1b000 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63  checkpoints-on-c
1b010 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74  lose, or zero (t
1b020 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74  he.** default) t
1b030 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20 54  o enable them. T
1b040 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1b050 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
1b060 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   to an integer.*
1b070 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20  * into which is 
1b080 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
1b090 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
1b0a0 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  er checkpoints-o
1b0b0 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20  n-close.** have 
1b0c0 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20  been disabled - 
1b0d0 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f  0 if they are no
1b0e0 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66  t disabled, 1 if
1b0f0 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f   they are..** </
1b100 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
1b110 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b120 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
1b130 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  BNAME           
1b140 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63   1000 /* const c
1b150 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  har* */.#define 
1b160 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1b170 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20  LOOKASIDE       
1b180 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f        1001 /* vo
1b190 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
1b1a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1b1b0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
1b1c0 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30  EY           100
1b1d0 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  2 /* int int* */
1b1e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b1f0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
1b200 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31  TRIGGER        1
1b210 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  003 /* int int* 
1b220 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b230 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1b240 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
1b250 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74   1004 /* int int
1b260 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1b270 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1b280 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
1b290 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69  ON 1005 /* int i
1b2a0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1b2b0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e  QLITE_DBCONFIG_N
1b2c0 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20  O_CKPT_ON_CLOSE 
1b2d0 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74       1006 /* int
1b2e0 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
1b2f0 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
1b300 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
1b310 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
1b320 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
1b330 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1b340 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1b350 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
1b360 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
1b370 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
1b380 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1b390 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
1b3a0 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
1b3b0 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
1b3c0 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
1b3d0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1b3e0 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
1b3f0 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
1b400 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  y..*/.SQLITE_API
1b410 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
1b420 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
1b430 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
1b440 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
1b450 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
1b460 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d  nsert Rowid.** M
1b470 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1b480 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
1b490 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20   in most SQLite 
1b4a0 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66  tables (except f
1b4b0 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  or [WITHOUT ROWI
1b4c0 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61  D] tables).** ha
1b4d0 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
1b4e0 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
1b4f0 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
1b500 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
1b510 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
1b520 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
1b530 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
1b540 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
1b550 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
1b560 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
1b570 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
1b580 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
1b590 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
1b5a0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
1b5b0 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
1b5c0 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
1b5d0 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
1b5e0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
1b5f0 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
1b600 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
1b610 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
1b620 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
1b630 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  The sqlite3_last
1b640 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
1b650 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1b660 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
1b670 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72  f the .** most r
1b680 65 63 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c  ecent successful
1b690 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61   [INSERT] into a
1b6a0 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20   rowid table or 
1b6b0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
1b6c0 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63  ** on database c
1b6d0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20  onnection D..** 
1b6e0 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57  ^Inserts into [W
1b6f0 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
1b700 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63  bles are not rec
1b710 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f  orded..** ^If no
1b720 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
1b730 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64  ERT]s into rowid
1b740 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20   tables.** have 
1b750 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
1b760 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1b770 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20  nnection D, .** 
1b780 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73  then sqlite3_las
1b790 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44  t_insert_rowid(D
1b7a0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
1b7b0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
1b7c0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
1b7d0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f  thin a trigger o
1b7e0 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74  r within a [virt
1b7f0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65  ual table].** me
1b800 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20  thod, then this 
1b810 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
1b820 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
1b830 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
1b840 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ** row as long a
1b850 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  s the trigger or
1b860 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
1b870 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67  ethod is running
1b880 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
1b890 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
1b8a0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
1b8b0 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75  d ends, the valu
1b8c0 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62  e returned .** b
1b8d0 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
1b8e0 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69  everts to what i
1b8f0 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65  t was before the
1b900 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
1b910 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74  ual.** table met
1b920 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a  hod began.)^.**.
1b930 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
1b940 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
1b950 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
1b960 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
1b970 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
1b980 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
1b990 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
1b9a0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1b9b0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
1b9c0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
1b9d0 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
1b9e0 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
1b9f0 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
1ba00 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
1ba10 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
1ba20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
1ba30 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
1ba40 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
1ba50 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
1ba60 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
1ba70 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
1ba80 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
1ba90 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
1baa0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
1bab0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
1bac0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
1bad0 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
1bae0 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
1baf0 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
1bb00 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
1bb10 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
1bb20 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
1bb30 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
1bb40 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
1bb50 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
1bb60 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
1bb70 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
1bb80 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
1bb90 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
1bba0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
1bbb0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
1bbc0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
1bbd0 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
1bbe0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
1bbf0 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
1bc00 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
1bc10 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
1bc20 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
1bc30 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1bc40 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
1bc50 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
1bc60 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
1bc70 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
1bc80 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
1bc90 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1bca0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
1bcb0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
1bcc0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
1bcd0 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
1bce0 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
1bcf0 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
1bd00 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
1bd10 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
1bd20 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
1bd30 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1bd40 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
1bd50 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
1bd60 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
1bd70 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
1bd80 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
1bd90 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
1bda0 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  wid]..*/.SQLITE_
1bdb0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
1bdc0 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
1bdd0 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
1bde0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1bdf0 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
1be00 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
1be10 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54   Modified.** MET
1be20 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1be30 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1be40 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
1be50 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
1be60 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20  ified, inserted 
1be70 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79  or.** deleted by
1be80 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1be90 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
1bea0 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44  ERT, UPDATE or D
1beb0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
1bec0 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  nt on the databa
1bed0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70  se connection sp
1bee0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f  ecified by the o
1bef0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  nly parameter..*
1bf00 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79  * ^Executing any
1bf10 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20 53   other type of S
1bf20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
1bf30 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  s not modify the
1bf40 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
1bf50 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
1bf60 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  ion..**.** ^Only
1bf70 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69   changes made di
1bf80 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e  rectly by the IN
1bf90 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
1bfa0 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
1bfb0 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72   are.** consider
1bfc0 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63  ed - auxiliary c
1bfd0 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
1bfe0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
1bff0 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a   | triggers], .*
1c000 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
1c010 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c  ctions] or [REPL
1c020 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
1c030 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e  resolution are n
1c040 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a  ot counted..** .
1c050 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20  ** Changes to a 
1c060 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
1c070 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a  tercepted by .**
1c080 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69   [INSTEAD OF tri
1c090 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f  gger | INSTEAD O
1c0a0 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65 20  F triggers] are 
1c0b0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68  not counted. ^Th
1c0c0 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75  e value .** retu
1c0d0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1c0e0 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69  changes() immedi
1c0f0 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49  ately after an I
1c100 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1c110 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74   .** DELETE stat
1c120 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76  ement run on a v
1c130 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65  iew is always ze
1c140 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73  ro. Only changes
1c150 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a   made to real .*
1c160 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75  * tables are cou
1c170 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e  nted..**.** Thin
1c180 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70  gs are more comp
1c190 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20 73  licated if the s
1c1a0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1c1b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
1c1c0 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20 61  executed while a
1c1d0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1c1e0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69   is running. Thi
1c1f0 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20  s may happen if 
1c200 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  the.** program u
1c210 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73  ses the [changes
1c220 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
1c230 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68  , or if some oth
1c240 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  er callback.** f
1c250 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  unction invokes 
1c260 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1c270 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65  ) directly. Esse
1c280 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20  ntially:.** .** 
1c290 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e  <ul>.**   <li> ^
1c2a0 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67  (Before entering
1c2b0 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
1c2c0 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  am the value ret
1c2d0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  urned by.**     
1c2e0 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67     sqlite3_chang
1c2f0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  es() function is
1c300 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74 68   saved. After th
1c310 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  e trigger progra
1c320 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73  m .**        has
1c330 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f   finished, the o
1c340 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73  riginal value is
1c350 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20   restored.)^.** 
1c360 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74  .**   <li> ^(Wit
1c370 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70 72  hin a trigger pr
1c380 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52  ogram each INSER
1c390 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44 45  T, UPDATE and DE
1c3a0 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20  LETE .**        
1c3b0 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74  statement sets t
1c3c0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1c3d0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
1c3e0 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20  nges() .**      
1c3f0 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f    upon completio
1c400 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20  n as normal. Of 
1c410 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c  course, this val
1c420 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c  ue will not incl
1c430 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61  ude .**        a
1c440 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f  ny changes perfo
1c450 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69 67  rmed by sub-trig
1c460 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c  gers, as the sql
1c470 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a  ite3_changes() .
1c480 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65 20  **        value 
1c490 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e  will be saved an
1c4a0 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65 72  d restored after
1c4b0 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67 65   each sub-trigge
1c4c0 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20  r has run.)^.** 
1c4d0 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68  </ul>.** .** ^Th
1c4e0 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66  is means that if
1c4f0 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20 53   the changes() S
1c500 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20  QL function (or 
1c510 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64  similar) is used
1c520 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73 74  .** by the first
1c530 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20   INSERT, UPDATE 
1c540 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  or DELETE statem
1c550 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72 69  ent within a tri
1c560 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74  gger, it .** ret
1c570 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61  urns the value a
1c580 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 63  s set when the c
1c590 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  alling statement
1c5a0 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67   began executing
1c5b0 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75  ..** ^If it is u
1c5c0 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  sed by the secon
1c5d0 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  d or subsequent 
1c5e0 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77  such statement w
1c5f0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
1c600 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65  .** program, the
1c610 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1c620 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d  reflects the num
1c630 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69  ber of rows modi
1c640 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20  fied by the .** 
1c650 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c  previous INSERT,
1c660 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54   UPDATE or DELET
1c670 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
1c680 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  in the same trig
1c690 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ger..**.** See a
1c6a0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1c6b0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1c6c0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
1c6d0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
1c6e0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
1c6f0 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53  the [changes() S
1c700 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1c710 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1c720 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1c730 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1c740 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1c750 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1c760 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
1c770 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
1c780 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65  hen the value re
1c790 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70  turned.** is unp
1c7a0 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
1c7b0 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
1c7c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1c7d0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1c7e0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1c7f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
1c800 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
1c810 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45  s Modified.** ME
1c820 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1c830 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1c840 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
1c850 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72  otal number of r
1c860 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f  ows inserted, mo
1c870 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  dified or.** del
1c880 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53  eted by all [INS
1c890 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f  ERT], [UPDATE] o
1c8a0 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
1c8b0 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a  ments completed.
1c8c0 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  ** since the dat
1c8d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c8e0 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63   was opened, inc
1c8f0 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65  luding those exe
1c900 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  cuted as.** part
1c910 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
1c920 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67  rams. ^Executing
1c930 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
1c940 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1c950 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66  .** does not aff
1c960 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  ect the value re
1c970 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1c980 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1c990 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67  )..** .** ^Chang
1c9a0 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  es made as part 
1c9b0 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  of [foreign key 
1c9c0 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63  actions] are inc
1c9d0 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  luded in the.** 
1c9e0 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65  count, but those
1c9f0 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
1ca00 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
1ca10 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
1ca20 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e  re.** not. ^Chan
1ca30 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
1ca40 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
1ca50 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46  ed by INSTEAD OF
1ca60 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72   triggers .** ar
1ca70 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
1ca80 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  * .** See also t
1ca90 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
1caa0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1cab0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
1cac0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
1cad0 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
1cae0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1caf0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
1cb00 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1cb10 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
1cb20 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
1cb30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cb40 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
1cb50 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1cb60 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
1cb70 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
1cb80 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
1cb90 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1cba0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
1cbb0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1cbc0 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
1cbd0 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
1cbe0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cbf0 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
1cc00 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
1cc10 72 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ry.** METHOD: sq
1cc20 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  lite3.**.** ^Thi
1cc30 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
1cc40 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
1cc50 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
1cc60 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
1cc70 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
1cc80 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
1cc90 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
1cca0 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
1ccb0 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
1ccc0 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
1ccd0 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
1cce0 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
1ccf0 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
1cd00 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
1cd10 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
1cd20 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
1cd30 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
1cd40 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61  .**.** ^It is sa
1cd50 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1cd60 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
1cd70 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
1cd80 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
1cd90 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
1cda0 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
1cdb0 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
1cdc0 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
1cdd0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
1cde0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
1cdf0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
1ce00 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
1ce10 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
1ce20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
1ce30 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
1ce40 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
1ce50 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  s..**.** ^If an 
1ce60 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1ce70 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
1ce80 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
1ce90 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
1cea0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
1ceb0 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
1cec0 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
1ced0 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
1cee0 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
1cef0 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
1cf00 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
1cf10 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  tion..**.** ^An 
1cf20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
1cf30 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
1cf40 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
1cf50 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
1cf60 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74  ..** ^If the int
1cf70 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
1cf80 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53  ration is an INS
1cf90 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
1cfa0 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69  DELETE.** that i
1cfb0 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
1cfc0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
1cfd0 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
1cfe0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a  e transaction.**
1cff0 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
1d000 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
1d010 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
1d020 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1d030 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65  (D) call is in e
1d040 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20  ffect until all 
1d050 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
1d060 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
1d070 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  nts on [database
1d080 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63   connection] D c
1d090 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e  omplete.  ^Any n
1d0a0 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
1d0b0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1d0c0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1d0d0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1d0e0 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
1d0f0 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
1d100 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
1d110 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
1d120 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
1d130 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
1d140 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
1d150 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
1d160 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
1d170 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74  .  ^New SQL stat
1d180 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1d190 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1d1a0 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
1d1b0 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
1d1c0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
1d1d0 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
1d1e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1d1f0 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20  errupt()..** ^A 
1d200 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1d210 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61  interrupt(D) tha
1d220 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68  t occurs when th
1d230 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69  ere are no runni
1d240 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
1d250 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20  ents is a no-op 
1d260 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63  and has no effec
1d270 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t on SQL stateme
1d280 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1d290 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1d2a0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1d2b0 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72  upt() call retur
1d2c0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ns..**.** If the
1d2d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d2e0 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
1d2f0 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
1d300 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75  rupt()].** is ru
1d310 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
1d320 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
1d330 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c  y happen..*/.SQL
1d340 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
1d350 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
1d360 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1d370 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
1d380 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
1d390 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
1d3a0 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
1d3b0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
1d3c0 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d  eful during comm
1d3d0 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
1d3e0 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
1d3f0 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
1d400 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65  entered text see
1d410 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d  ms to form a com
1d420 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
1d430 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64  ent or.** if add
1d440 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73  itional input is
1d450 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73   needed before s
1d460 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20  ending the text 
1d470 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
1d480 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68  or parsing.  ^Th
1d490 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1d4a0 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70  urn 1 if the inp
1d4b0 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70  ut string.** app
1d4c0 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d  ears to be a com
1d4d0 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
1d4e0 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65  ent.  ^A stateme
1d4f0 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
1d500 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
1d510 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
1d520 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
1d530 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72   and is not a pr
1d540 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c  efix of a.** wel
1d550 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20  l-formed CREATE 
1d560 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
1d570 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20  t.  ^Semicolons 
1d580 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
1d590 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
1d5a0 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
1d5b0 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
1d5c0 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
1d5d0 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
1d5e0 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
1d5f0 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
1d600 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
1d610 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
1d620 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
1d630 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
1d640 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
1d650 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57   terminator.  ^W
1d660 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64  hitespace.** and
1d670 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66   comments that f
1d680 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20  ollow the final 
1d690 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67  semicolon are ig
1d6a0 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nored..**.** ^Th
1d6b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
1d6c0 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
1d6d0 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
1d6e0 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20  lete.  ^If a.** 
1d6f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1d700 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51  n fails, then SQ
1d710 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65  LITE_NOMEM is re
1d720 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
1d730 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
1d740 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
1d750 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
1d760 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
1d770 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
1d780 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
1d790 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  L..**.** ^(If SQ
1d7a0 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65  Lite has not bee
1d7b0 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73  n initialized us
1d7c0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ing [sqlite3_ini
1d7d0 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72  tialize()] prior
1d7e0 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67   .** to invoking
1d7f0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1d800 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74  e16() then sqlit
1d810 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
1d820 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75  is invoked.** au
1d830 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
1d840 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1d850 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e  6().  If that in
1d860 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69  itialization fai
1d870 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ls,.** then the 
1d880 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
1d890 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  m sqlite3_comple
1d8a0 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e  te16() will be n
1d8b0 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72  on-zero.** regar
1d8c0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1d8d0 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75   or not the inpu
1d8e0 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74  t SQL is complet
1d8f0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  e.)^.**.** The i
1d900 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1d910 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
1d920 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
1d930 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
1d940 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
1d950 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
1d960 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1d970 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
1d980 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
1d990 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
1d9a0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1d9b0 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  r..*/.SQLITE_API
1d9c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d   int sqlite3_com
1d9d0 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
1d9e0 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   *sql);.SQLITE_A
1d9f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
1da00 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
1da10 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
1da20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
1da30 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
1da40 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
1da50 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
1da60 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75 73 79   KEYWORDS: {busy
1da70 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
1da80 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c 65 72  k} {busy handler
1da90 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
1daa0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ite3.**.** ^The 
1dab0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1dac0 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74  dler(D,X,P) rout
1dad0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
1dae0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a  ack function X.*
1daf0 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  * that might be 
1db00 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67  invoked with arg
1db10 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72  ument P whenever
1db20 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
1db30 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73  s made to access
1db40 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c   a database tabl
1db50 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  e associated wit
1db60 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
1db70 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65  onnection] D whe
1db80 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  n another thread
1db90 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
1dba0 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63  as the table loc
1dbb0 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ked..** The sqli
1dbc0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1dbd0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
1dbe0 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1dbf0 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  t.** [sqlite3_bu
1dc00 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e  sy_timeout()] an
1dc10 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  d [PRAGMA busy_t
1dc20 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  imeout]..**.** ^
1dc30 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1dc40 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
1dc50 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
1dc60 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
1dc70 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
1dc80 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
1dc90 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
1dca0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
1dcb0 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
1dcc0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
1dcd0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
1dce0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
1dcf0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
1dd00 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1dd10 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
1dd20 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
1dd30 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
1dd40 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
1dd50 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
1dd60 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
1dd70 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
1dd80 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
1dd90 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
1dda0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
1ddb0 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
1ddc0 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
1ddd0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1dde0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
1ddf0 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ked previously f
1de00 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b  or the same lock
1de10 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
1de20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
1de30 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
1de40 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
1de50 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
1de60 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
1de70 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1de80 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
1de90 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20   is returned.** 
1dea0 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  to the applicati
1deb0 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63  on..** ^If the c
1dec0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1ded0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61  non-zero, then a
1dee0 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a  nother attempt.*
1def0 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63  * is made to acc
1df00 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1df10 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72   and the cycle r
1df20 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  epeats..**.** Th
1df30 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20  e presence of a 
1df40 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65  busy handler doe
1df50 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20  s not guarantee 
1df60 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20  that it will be 
1df70 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20  invoked.** when 
1df80 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f  there is lock co
1df90 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51  ntention. ^If SQ
1dfa0 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20  Lite determines 
1dfb0 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  that invoking th
1dfc0 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65  e busy.** handle
1dfd0 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  r could result i
1dfe0 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74  n a deadlock, it
1dff0 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61   will go ahead a
1e000 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
1e010 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68  E_BUSY].** to th
1e020 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e  e application in
1e030 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
1e040 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68  g the .** busy h
1e050 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69  andler..** Consi
1e060 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77  der a scenario w
1e070 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73  here one process
1e080 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1e090 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20  ad lock that.** 
1e0a0 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20  it is trying to 
1e0b0 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73  promote to a res
1e0c0 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a  erved lock and.*
1e0d0 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  * a second proce
1e0e0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1e0f0 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68  reserved lock th
1e100 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a  at it is trying.
1e110 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ** to promote to
1e120 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f   an exclusive lo
1e130 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70  ck.  The first p
1e140 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72  rocess cannot pr
1e150 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65  oceed.** because
1e160 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62   it is blocked b
1e170 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  y the second and
1e180 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1e190 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72  ess cannot.** pr
1e1a0 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74  oceed because it
1e1b0 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74   is blocked by t
1e1c0 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f  he first.  If bo
1e1d0 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20  th processes.** 
1e1e0 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20  invoke the busy 
1e1f0 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65  handlers, neithe
1e200 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20  r will make any 
1e210 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65  progress.  There
1e220 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  fore,.** SQLite 
1e230 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1e240 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69  BUSY] for the fi
1e250 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70  rst process, hop
1e260 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a  ing that this.**
1e270 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65   will induce the
1e280 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74   first process t
1e290 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65  o release its re
1e2a0 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f  ad lock and allo
1e2b0 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  w.** the second 
1e2c0 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65  process to proce
1e2d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64  ed..**.** ^The d
1e2e0 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c  efault busy call
1e2f0 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a  back is NULL..**
1e300 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20  .** ^(There can 
1e310 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65  only be a single
1e320 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65   busy handler de
1e330 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a  fined for each.*
1e340 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1e350 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e  ection].  Settin
1e360 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e  g a new busy han
1e370 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a  dler clears any.
1e380 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1e390 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e  t handler.)^  ^N
1e3a0 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67  ote that calling
1e3b0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1e3c0 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20  imeout()].** or 
1e3d0 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47  evaluating [PRAG
1e3e0 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d  MA busy_timeout=
1e3f0 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74  N] will change t
1e400 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  he.** busy handl
1e410 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61  er and thus clea
1e420 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79  r any previously
1e430 20 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65   set busy handle
1e440 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
1e450 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
1e460 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
1e470 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
1e480 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
1e490 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1e4a0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1e4b0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49  busy handler.  I
1e4c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a  n other words,.*
1e4d0 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
1e4e0 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  er is not reentr
1e4f0 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ant.  Any such a
1e500 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
1e510 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
1e520 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
1e530 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
1e540 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
1e550 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1e560 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
1e570 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e580 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
1e590 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1e5a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1e5b0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1e5c0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 69  ndler(sqlite3*,i
1e5d0 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
1e5e0 2c 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ,void*);../*.** 
1e5f0 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20  CAPI3REF: Set A 
1e600 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20  Busy Timeout.** 
1e610 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1e620 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1e630 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69  ine sets a [sqli
1e640 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1e650 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d   | busy handler]
1e660 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20   that sleeps.** 
1e670 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20  for a specified 
1e680 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77  amount of time w
1e690 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c  hen a table is l
1e6a0 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e  ocked.  ^The han
1e6b0 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65  dler.** will sle
1e6c0 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65  ep multiple time
1e6d0 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74  s until at least
1e6e0 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1e6f0 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a  ds of sleeping.*
1e700 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74  * have accumulat
1e710 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c  ed.  ^After at l
1e720 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1e730 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1e740 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c  ng,.** the handl
1e750 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69  er returns 0 whi
1e760 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74  ch causes [sqlit
1e770 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65  e3_step()] to re
1e780 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
1e790 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  BUSY]..**.** ^Ca
1e7a0 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69  lling this routi
1e7b0 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d  ne with an argum
1e7c0 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  ent less than or
1e7d0 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a   equal to zero.*
1e7e0 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20  * turns off all 
1e7f0 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a  busy handlers..*
1e800 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1e810 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1e820 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66  e busy handler f
1e830 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  or a particular.
1e840 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1e850 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20  nection] at any 
1e860 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49  given moment.  I
1e870 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68  f another busy h
1e880 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65  andler.** was de
1e890 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73  fined  (using [s
1e8a0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1e8b0 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f  ler()]) prior to
1e8c0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73   calling.** this
1e8d0 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f   routine, that o
1e8e0 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1e8f0 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a  r is cleared.)^.
1e900 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
1e910 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1e920 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45  meout].*/.SQLITE
1e930 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1e940 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
1e950 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
1e960 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e970 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
1e980 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
1e990 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45  ng Queries.** ME
1e9a0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1e9b0 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
1e9c0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
1e9d0 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
1e9e0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1e9f0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1ea00 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
1ea10 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
1ea20 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1ea30 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
1ea40 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
1ea50 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
1ea60 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
1ea70 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
1ea80 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1ea90 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
1eaa0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
1eab0 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
1eac0 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
1ead0 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
1eae0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
1eaf0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
1eb00 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
1eb10 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
1eb20 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
1eb30 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
1eb40 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
1eb50 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1eb60 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
1eb70 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
1eb80 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
1eb90 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
1eba0 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1ebb0 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
1ebc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1ebd0 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
1ebe0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1ebf0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
1ec00 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
1ec10 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1ec20 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
1ec30 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
1ec40 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
1ec50 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
1ec60 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
1ec70 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
1ec80 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1ec90 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
1eca0 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
1ecb0 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
1ecc0 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
1ecd0 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
1ece0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
1ecf0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
1ed00 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
1ed10 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
1ed20 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
1ed30 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
1ed40 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1ed50 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
1ed60 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
1ed70 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1ed80 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
1ed90 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
1eda0 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
1edb0 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
1edc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
1edd0 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
1ede0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
1edf0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
1ee00 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1ee10 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
1ee20 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
1ee30 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
1ee40 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1ee50 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
1ee60 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
1ee70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
1ee80 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
1ee90 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
1eea0 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
1eeb0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1eec0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1eed0 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
1eee0 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
1eef0 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
1ef00 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
1ef10 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
1ef20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
1ef30 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
1ef40 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
1ef50 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
1ef60 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1ef70 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
1ef80 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
1ef90 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
1efa0 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
1efb0 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
1efc0 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
1efd0 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
1efe0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1eff0 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
1f000 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
1f010 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
1f020 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
1f030 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
1f040 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1f050 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
1f060 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
1f070 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
1f080 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1f090 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
1f0a0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1f0b0 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
1f0c0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1f0d0 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
1f0e0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1f0f0 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
1f100 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
1f110 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
1f120 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
1f130 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
1f140 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
1f150 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1f160 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
1f170 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1f180 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1f190 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1f1a0 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
1f1b0 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
1f1c0 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
1f1d0 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
1f1e0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1f1f0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
1f200 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
1f210 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
1f220 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
1f230 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
1f240 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
1f250 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
1f260 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
1f270 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
1f280 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
1f290 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
1f2a0 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
1f2b0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1f2c0 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
1f2d0 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
1f2e0 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
1f2f0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1f300 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
1f310 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
1f320 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
1f330 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
1f340 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
1f350 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
1f360 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
1f370 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
1f380 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
1f390 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
1f3a0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
1f3b0 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
1f3c0 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
1f3d0 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
1f3e0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1f3f0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
1f400 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1f410 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
1f420 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
1f430 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1f440 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
1f450 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
1f460 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1f470 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
1f480 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
1f490 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1f4a0 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
1f4b0 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
1f4c0 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
1f4d0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1f4e0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
1f4f0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
1f500 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
1f510 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
1f520 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
1f530 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
1f540 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
1f550 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
1f560 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
1f570 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
1f580 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
1f590 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
1f5a0 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
1f5b0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1f5c0 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
1f5d0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1f5e0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
1f5f0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  I int sqlite3_ge
1f600 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
1f610 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
1f620 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
1f630 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
1f640 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
1f650 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
1f660 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
1f670 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
1f680 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
1f690 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
1f6a0 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
1f6b0 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1f6c0 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
1f6d0 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
1f6e0 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
1f6f0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1f700 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
1f710 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1f720 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
1f730 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
1f740 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
1f750 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  ere */.);.SQLITE
1f760 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
1f770 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
1f780 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
1f790 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
1f7a0 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
1f7b0 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
1f7c0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1f7d0 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d  utines are work-
1f7e0 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
1f7f0 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
1f800 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
1f810 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
1f820 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
1f830 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75  These routines u
1f840 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f  nderstand most o
1f850 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52  f the common K&R
1f860 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1f870 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d  ons,.** plus som
1f880 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e  e additional non
1f890 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74  -standard format
1f8a0 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f  s, detailed belo
1f8b0 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  w..** Note that 
1f8c0 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65  some of the more
1f8d0 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74   obscure formatt
1f8e0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d  ing options from
1f8f0 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62   recent.** C-lib
1f900 72 61 72 79 20 73 74 61 6e 64 61 72 64 73 20 61  rary standards a
1f910 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  re omitted from 
1f920 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74  this implementat
1f930 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
1f940 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1f950 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
1f960 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1f970 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
1f980 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
1f990 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
1f9a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
1f9b0 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
1f9c0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1f9d0 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
1f9e0 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
1f9f0 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
1fa00 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
1fa10 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
1fa20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
1fa30 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
1fa40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
1fa50 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
1fa60 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
1fa70 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1fa80 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
1fa90 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ng..**.** ^(The 
1faa0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1fab0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
1fac0 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
1fad0 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
1fae0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1faf0 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
1fb00 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
1fb10 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
1fb20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
1fb30 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1fb40 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
1fb50 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
1fb60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
1fb70 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
1fb80 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
1fb90 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
1fba0 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
1fbb0 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
1fbc0 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
1fbd0 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
1fbe0 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
1fbf0 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
1fc00 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
1fc10 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1fc20 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
1fc30 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
1fc40 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
1fc50 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1fc60 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
1fc70 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
1fc80 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
1fc90 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
1fca0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
1fcb0 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
1fcc0 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
1fcd0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
1fce0 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
1fcf0 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
1fd00 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
1fd10 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
1fd20 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
1fd30 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
1fd40 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1fd50 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
1fd60 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
1fd70 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
1fd80 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
1fd90 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
1fda0 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
1fdb0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1fdc0 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
1fdd0 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
1fde0 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
1fdf0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
1fe00 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1fe10 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
1fe20 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
1fe30 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
1fe40 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
1fe50 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
1fe60 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
1fe70 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
1fe80 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
1fe90 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
1fea0 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
1feb0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  acters..**.** ^T
1fec0 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  he sqlite3_vsnpr
1fed0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1fee0 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73  s a varargs vers
1fef0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1ff00 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a  nprintf()..**.**
1ff10 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1ff20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
1ff30 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
1ff40 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
1ff50 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
1ff60 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
1ff70 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
1ff80 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
1ff90 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
1ffa0 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
1ffb0 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
1ffc0 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
1ffd0 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
1ffe0 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22  "%Q", "%w" and "
1fff0 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
20000 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
20010 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
20020 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
20030 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
20040 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
20050 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
20060 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
20070 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
20080 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
20090 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
200a0 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
200b0 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
200c0 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
200d0 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
200e0 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
200f0 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
20100 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
20110 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
20120 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
20130 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
20140 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
20150 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
20160 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
20170 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
20180 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
20190 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
201a0 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
201b0 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
201c0 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
201d0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
201e0 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
201f0 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
20200 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
20210 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
20220 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
20230 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
20240 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
20250 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
20260 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
20270 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
20280 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
20290 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
202a0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
202b0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
202c0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
202d0 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
202e0 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
202f0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
20300 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
20310 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
20320 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
20330 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
20340 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
20350 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
20360 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
20370 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
20380 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
20390 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
203a0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
203b0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
203c0 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
203d0 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
203e0 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
203f0 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
20400 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
20410 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
20420 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
20430 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
20440 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
20450 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
20460 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
20470 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
20480 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
20490 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
204a0 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
204b0 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
204c0 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
204d0 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
204e0 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
204f0 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
20500 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
20510 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
20520 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
20530 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
20540 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
20550 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
20560 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
20570 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
20580 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
20590 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
205a0 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
205b0 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
205c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
205d0 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
205e0 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
205f0 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
20600 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
20610 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
20620 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
20630 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
20640 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
20650 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
20660 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
20670 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
20680 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
20690 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
206a0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
206b0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
206c0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
206d0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
206e0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
206f0 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
20700 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
20710 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
20720 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
20730 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
20740 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
20750 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
20760 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
20770 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  w" formatting op
20780 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71  tion is like "%q
20790 22 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  " except that it
207a0 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62   expects to.** b
207b0 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68  e contained with
207c0 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73  in double-quotes
207d0 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67   instead of sing
207e0 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69  le quotes, and i
207f0 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65  t.** escapes the
20800 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68   double-quote ch
20810 61 72 61 63 74 65 72 20 69 6e 73 74 65 61 64 20  aracter instead 
20820 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75  of the single-qu
20830 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  ote.** character
20840 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f  .)^  The "%w" fo
20850 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
20860 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
20870 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67  safely inserting
20880 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  .** table and co
20890 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20  lumn names into 
208a0 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51  a constructed SQ
208b0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  L statement..**.
208c0 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f  ** ^(The "%z" fo
208d0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
208e0 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20  works like "%s" 
208f0 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  but with the.** 
20900 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
20910 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
20920 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
20930 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
20940 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
20950 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
20960 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
20970 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f  put string.)^.*/
20980 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
20990 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
209a0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
209b0 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .);.SQLITE_API c
209c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
209d0 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
209e0 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c  *, va_list);.SQL
209f0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
20a00 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
20a10 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
20a20 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49  har*, ...);.SQLI
20a30 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
20a40 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
20a50 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
20a60 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
20a70 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20a80 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
20a90 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
20aa0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
20ab0 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
20ac0 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
20ad0 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
20ae0 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
20af0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
20b00 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
20b10 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
20b20 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
20b30 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
20b40 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
20b50 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
20b60 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
20b70 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
20b80 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
20b90 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
20ba0 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
20bb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
20bc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
20bd0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
20be0 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
20bf0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
20c00 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
20c10 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
20c20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
20c30 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
20c40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
20c50 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
20c60 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
20c70 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
20c80 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
20c90 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
20ca0 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
20cb0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
20cc0 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
20cd0 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
20ce0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
20cf0 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
20d00 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
20d10 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
20d20 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f  64(N) routine wo
20d30 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a  rks just like.**
20d40 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
20d50 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
20d60 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20   is an unsigned 
20d70 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69  64-bit integer i
20d80 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73  nstead.** of a s
20d90 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74  igned 32-bit int
20da0 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  eger..**.** ^Cal
20db0 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
20dc0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
20dd0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
20de0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
20df0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
20e00 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
20e10 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
20e20 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
20e30 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
20e40 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
20e50 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
20e60 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
20e70 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
20e80 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
20e90 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
20ea0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
20eb0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
20ec0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
20ed0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
20ee0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
20ef0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
20f00 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
20f10 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
20f20 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
20f30 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
20f40 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
20f50 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
20f60 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
20f70 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
20f80 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
20f90 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
20fa0 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
20fb0 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
20fc0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
20fd0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
20fe0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
20ff0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
21000 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
21010 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
21020 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
21030 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
21040 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
21050 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
21060 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
21070 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
21080 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
21090 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62  llocation X to b
210a0 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
210b0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58  es..** ^If the X
210c0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
210d0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
210e0 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  N).** is a NULL 
210f0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
21100 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
21110 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
21120 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
21130 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74  loc(N)..** ^If t
21140 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74  he N parameter t
21150 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
21160 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f  c(X,N) is zero o
21170 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
21180 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
21190 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
211a0 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
211b0 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58  * sqlite3_free(X
211c0 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
211d0 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75  ealloc(X,N) retu
211e0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
211f0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
21200 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  tion.** of at le
21210 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73  ast N bytes in s
21220 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69  ize or NULL if i
21230 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f  nsufficient memo
21240 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e  ry is available.
21250 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65  .** ^If M is the
21260 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69   size of the pri
21270 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74  or allocation, t
21280 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74  hen min(N,M) byt
21290 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69  es.** of the pri
212a0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72  or allocation ar
212b0 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68  e copied into th
212c0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62  e beginning of b
212d0 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  uffer returned.*
212e0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61  * by sqlite3_rea
212f0 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68  lloc(X,N) and th
21300 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
21310 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20  on is freed..** 
21320 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  ^If sqlite3_real
21330 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73  loc(X,N) returns
21340 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70   NULL and N is p
21350 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68  ositive, then th
21360 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63  e.** prior alloc
21370 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65  ation is not fre
21380 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
21390 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
213a0 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73  (X,N) interfaces
213b0 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20   works the same 
213c0 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  as.** sqlite3_re
213d0 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70  alloc(X,N) excep
213e0 74 20 74 68 61 74 20 4e 20 69 73 20 61 20 36 34  t that N is a 64
213f0 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e  -bit unsigned in
21400 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
21410 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
21420 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  ned integer..**.
21430 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65  ** ^If X is a me
21440 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
21450 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
21460 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
21470 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71  _malloc(),.** sq
21480 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29  lite3_malloc64()
21490 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  , sqlite3_reallo
214a0 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  c(), or sqlite3_
214b0 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65  realloc64(), the
214c0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
214d0 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 74 68  ze(X) returns th
214e0 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d  e size of that m
214f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
21500 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54   in bytes..** ^T
21510 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
21520 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69  d by sqlite3_msi
21530 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c  ze(X) might be l
21540 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e  arger than the n
21550 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65  umber.** of byte
21560 73 20 72 65 71 75 65 73 74 65 64 20 77 68 65 6e  s requested when
21570 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64   X was allocated
21580 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55  .  ^If X is a NU
21590 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a  LL pointer then.
215a0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
215b0 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (X) returns zero
215c0 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74  .  If X points t
215d0 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74  o something that
215e0 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62   is not.** the b
215f0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f  eginning of memo
21600 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f  ry allocation, o
21610 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74  r if it points t
21620 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20  o a formerly.** 
21630 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  valid memory all
21640 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73  ocation that has
21650 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c   now been freed,
21660 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
21670 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  or.** of sqlite3
21680 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64  _msize(X) is und
21690 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69  efined and possi
216a0 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
216b0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
216c0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
216d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c  e3_malloc(), sql
216e0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a  ite3_realloc(),.
216f0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
21700 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  c64(), and sqlit
21710 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a  e3_realloc64().*
21720 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67  * is always alig
21730 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20  ned to at least 
21740 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61  an 8 byte bounda
21750 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34  ry, or to a.** 4
21760 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69   byte boundary i
21770 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f  f the [SQLITE_4_
21780 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c  BYTE_ALIGNED_MAL
21790 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  LOC] compile-tim
217a0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75  e.** option is u
217b0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51  sed..**.** In SQ
217c0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
217d0 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74  .0 and 3.5.1, it
217e0 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f   was possible to
217f0 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53   define.** the S
21800 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52  QLITE_OMIT_MEMOR
21810 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69  Y_ALLOCATION whi
21820 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74  ch would cause t
21830 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69  he built-in.** i
21840 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
21850 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
21860 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20  to be omitted.  
21870 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a  That capability.
21880 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ** is no longer 
21890 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20  provided.  Only 
218a0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
218b0 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62  allocators can b
218c0 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72  e used..**.** Pr
218d0 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65  ior to SQLite ve
218e0 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68  rsion 3.7.10, th
218f0 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74  e Windows OS int
21900 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c  erface layer cal
21910 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65  led.** the syste
21920 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  m malloc() and f
21930 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77  ree() directly w
21940 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a  hen converting.*
21950 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77  * filenames betw
21960 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e  een the UTF-8 en
21970 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53  coding used by S
21980 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61  QLite.** and wha
21990 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65  tever filename e
219a0 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20  ncoding is used 
219b0 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  by the particula
219c0 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73  r Windows.** ins
219d0 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f  tallation.  Memo
219e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
219f0 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74  rors were detect
21a00 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20  ed, but.** they 
21a10 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61  were reported ba
21a20 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41  ck as [SQLITE_CA
21a30 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53  NTOPEN] or.** [S
21a40 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74  QLITE_IOERR] rat
21a50 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
21a60 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54  _NOMEM]..**.** T
21a70 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  he pointer argum
21a80 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  ents to [sqlite3
21a90 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71  _free()] and [sq
21aa0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
21ab0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
21ac0 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20  er NULL or else 
21ad0 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65  pointers obtaine
21ae0 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a  d from a prior.*
21af0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  * invocation of 
21b00 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
21b10 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
21b20 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68  ealloc()] that h
21b30 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62  ave.** not yet b
21b40 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a  een released..**
21b50 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
21b60 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61  ion must not rea
21b70 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70  d or write any p
21b80 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63  art of.** a bloc
21b90 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65  k of memory afte
21ba0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65  r it has been re
21bb0 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20  leased using.** 
21bc0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
21bd0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
21be0 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  lloc()]..*/.SQLI
21bf0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
21c00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
21c10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
21c20 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
21c30 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74  c64(sqlite3_uint
21c40 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
21c50 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
21c60 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
21c70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
21c80 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
21c90 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c  loc64(void*, sql
21ca0 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51  ite3_uint64);.SQ
21cb0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
21cc0 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a  lite3_free(void*
21cd0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
21ce0 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 73 71 6c  lite3_uint64 sql
21cf0 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69 64 2a  ite3_msize(void*
21d00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21d10 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
21d20 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a  ator Statistics.
21d30 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f  **.** SQLite pro
21d40 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20  vides these two 
21d50 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72  interfaces for r
21d60 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20  eporting on the 
21d70 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65  status.** of the
21d80 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
21d90 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72  ()], [sqlite3_fr
21da0 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ee()], and [sqli
21db0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
21dc0 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63  * routines, whic
21dd0 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74  h form the built
21de0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
21df0 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e  ation subsystem.
21e00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
21e10 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
21e20 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ()] routine retu
21e30 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
21e40 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65  f bytes.** of me
21e50 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f  mory currently o
21e60 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c  utstanding (mall
21e70 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65  oced but not fre
21e80 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ed)..** ^The [sq
21e90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
21ea0 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e  hwater()] routin
21eb0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61  e returns the ma
21ec0 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f  ximum.** value o
21ed0 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  f [sqlite3_memor
21ee0 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20  y_used()] since 
21ef0 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
21f00 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20  ark.** was last 
21f10 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c  reset.  ^The val
21f20 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
21f30 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
21f40 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b  used()] and.** [
21f50 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
21f60 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c  ighwater()] incl
21f70 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64  ude any overhead
21f80 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c  .** added by SQL
21f90 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65  ite in its imple
21fa0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71  mentation of [sq
21fb0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
21fc0 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72  .** but not over
21fd0 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68  head added by th
21fe0 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67  e any underlying
21ff0 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a   system library.
22000 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  ** routines that
22010 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
22020 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a  ()] may call..**
22030 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
22040 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20  high-water mark 
22050 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20  is reset to the 
22060 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
22070 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
22080 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61  ory_used()] if a
22090 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70  nd only if the p
220a0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
220b0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
220c0 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74  ighwater()] is t
220d0 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  rue.  ^The value
220e0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
220f0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
22100 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73  highwater(1)] is
22110 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
22120 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  mark.** prior to
22130 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53   the reset..*/.S
22140 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
22150 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
22160 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
22170 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
22180 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
22190 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
221a0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
221b0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
221c0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
221d0 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
221e0 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
221f0 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
22200 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
22210 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
22220 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
22230 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
22240 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
22250 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
22260 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
22270 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
22280 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
22290 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
222a0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
222b0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
222c0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
222d0 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
222e0 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
222f0 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
22300 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
22310 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
22320 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
22330 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
22340 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
22350 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
22360 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
22370 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
22380 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
22390 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
223a0 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  er P..** ^The P 
223b0 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65  parameter can be
223c0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
223d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20  .**.** ^If this 
223e0 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20  routine has not 
223f0 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  been previously 
22400 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65  called or if the
22410 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c   previous.** cal
22420 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61  l had N less tha
22430 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20  n one or a NULL 
22440 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74  pointer for P, t
22450 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a  hen the PRNG is.
22460 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  ** seeded using 
22470 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
22480 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61  ned from the xRa
22490 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
224a0 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  of.** the defaul
224b0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
224c0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74  object..** ^If t
224d0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
224e0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
224f0 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f   had an N of 1 o
22500 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20  r more and a.** 
22510 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20  non-NULL P then 
22520 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
22530 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
22540 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
22550 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
22560 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
22570 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
22580 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
22590 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
225a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
225b0 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
225c0 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
225d0 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
225e0 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
225f0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
22600 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
22610 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  3.**.** ^This ro
22620 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
22630 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  an authorizer ca
22640 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
22650 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
22660 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22670 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
22680 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
22690 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
226a0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
226b0 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
226c0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
226d0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
226e0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
226f0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
22700 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
22710 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
22720 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
22730 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
22740 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
22750 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v2()].  ^At var
22760 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
22770 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
22780 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
22790 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
227a0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
227b0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
227c0 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
227d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
227e0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
227f0 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
22800 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
22810 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
22820 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
22830 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
22840 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
22850 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
22860 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
22870 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
22880 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
22890 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
228a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
228b0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
228c0 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
228d0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
228e0 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
228f0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
22900 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
22910 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
22920 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
22930 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
22940 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
22950 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
22960 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
22970 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
22980 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
22990 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
229a0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
229b0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
229c0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
229d0 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
229e0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
229f0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
22a00 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
22a10 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
22a20 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
22a30 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
22a40 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
22a50 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
22a60 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
22a70 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
22a80 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
22a90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22aa0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
22ab0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
22ac0 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
22ad0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
22ae0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
22af0 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
22b00 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
22b10 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
22b20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
22b30 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
22b40 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
22b50 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
22b60 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
22b70 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
22b80 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
22b90 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
22ba0 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
22bb0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
22bc0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
22bd0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
22be0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
22bf0 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
22c00 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
22c10 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
22c20 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
22c30 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
22c40 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
22c50 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
22c60 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
22c70 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
22c80 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
22c90 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
22ca0 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
22cb0 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
22cc0 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
22cd0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
22ce0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
22cf0 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
22d00 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
22d10 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
22d20 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
22d30 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
22d40 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
22d50 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
22d60 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
22d70 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
22d80 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
22d90 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
22da0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
22db0 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
22dc0 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
22dd0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
22de0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
22df0 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
22e00 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
22e10 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
22e20 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
22e30 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
22e40 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  a table..** ^If 
22e50 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
22e60 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
22e70 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
22e80 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
22e90 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
22ea0 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
22eb0 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
22ec0 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
22ed0 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
22ee0 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
22ef0 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
22f00 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
22f10 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
22f20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
22f30 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
22f40 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
22f50 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
22f60 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
22f70 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
22f80 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
22f90 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
22fa0 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
22fb0 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
22fc0 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
22fd0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
22fe0 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
22ff0 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
23000 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
23010 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
23020 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
23030 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
23040 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
23050 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
23060 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
23070 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
23080 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
23090 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
230a0 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
230b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
230c0 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
230d0 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
230e0 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
230f0 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
23100 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
23110 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
23120 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
23130 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
23140 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
23150 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
23160 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23170 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
23180 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
23190 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
231a0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
231b0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
231c0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
231d0 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
231e0 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
231f0 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
23200 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
23210 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
23220 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
23230 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
23240 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
23250 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
23260 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
23270 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
23280 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
23290 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
232a0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
232b0 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  ^(Only a single 
232c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
232d0 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
232e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
232f0 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
23300 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
23310 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
23320 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
23330 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
23340 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62   call.)^  ^Disab
23350 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
23360 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
23370 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
23380 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
23390 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
233a0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
233b0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
233c0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
233d0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
233e0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
233f0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
23400 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
23410 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
23420 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
23430 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
23440 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
23450 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
23460 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
23470 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
23480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23490 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
234a0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
234b0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
234c0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73  ..**.** ^When [s
234d0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
234e0 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
234f0 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
23500 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
23510 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
23520 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
23530 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
23540 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
23550 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
23560 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
23570 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
23580 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
23590 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
235a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
235b0 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
235c0 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
235d0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
235e0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
235f0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
23600 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
23610 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
23620 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
23630 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
23640 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
23650 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
23660 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
23670 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
23680 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
23690 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
236a0 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
236b0 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
236c0 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
236d0 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
236e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
236f0 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
23700 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
23710 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
23720 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  nge..*/.SQLITE_A
23730 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
23740 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
23750 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
23760 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
23770 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
23780 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
23790 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
237a0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
237b0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
237c0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
237d0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
237e0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
237f0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
23800 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
23810 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
23820 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
23830 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
23840 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
23850 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
23860 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
23870 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
23880 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
23890 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
238a0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
238b0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
238c0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
238d0 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
238e0 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
238f0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
23900 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
23910 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
23920 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
23930 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c  used as a [confl
23940 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d  ict resolution m
23950 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ode].** returned
23960 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
23970 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
23980 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
23990 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
239a0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
239b0 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
239c0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
239d0 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
239e0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
239f0 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
23a00 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
23a10 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
23a20 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
23a30 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
23a40 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
23a50 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
23a60 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
23a70 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
23a80 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
23a90 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
23aa0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
23ab0 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
23ac0 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
23ad0 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
23ae0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
23af0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
23b00 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
23b10 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
23b20 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
23b30 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
23b40 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
23b50 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
23b60 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
23b70 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
23b80 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
23b90 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
23ba0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
23bb0 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
23bc0 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
23bd0 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
23be0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
23bf0 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
23c00 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
23c10 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
23c20 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
23c30 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
23c40 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
23c50 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
23c60 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
23c70 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
23c80 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
23c90 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
23ca0 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
23cb0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
23cc0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
23cd0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
23ce0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
23cf0 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
23d00 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
23d10 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
23d20 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
23d30 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
23d40 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
23d50 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
23d60 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
23d70 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
23d80 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
23d90 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
23da0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
23db0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
23dc0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
23dd0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
23de0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
23df0 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
23e00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23e10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
23e20 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
23e30 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
23e40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
23e50 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
23e60 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
23e70 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
23e80 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
23e90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
23ea0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
23eb0 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
23ec0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
23ed0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
23ee0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
23ef0 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
23f00 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
23f10 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
23f20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
23f30 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
23f40 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
23f50 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
23f60 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
23f70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
23f80 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
23f90 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
23fa0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
23fb0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
23fc0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
23fd0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
23fe0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
23ff0 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
24000 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
24010 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
24020 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
24030 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
24040 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
24050 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
24060 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
24070 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
24080 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
24090 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
240a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
240b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
240c0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
240d0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
240e0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
240f0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
24100 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24110 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
24120 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
24130 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
24140 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
24150 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24160 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
24170 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
24180 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
24190 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
241a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
241b0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
241c0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
241d0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
241e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
241f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24200 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
24210 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
24220 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
24230 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
24240 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24250 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
24260 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
24270 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
24280 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
24290 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
242a0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
242b0 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
242c0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
242d0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
242e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
242f0 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
24300 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
24310 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
24320 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
24330 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
24340 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
24350 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
24360 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
24370 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
24380 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
24390 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
243a0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
243b0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
243c0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
243d0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
243e0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
243f0 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
24400 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
24410 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
24420 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
24430 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
24440 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
24450 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
24460 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
24470 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
24480 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
24490 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
244a0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
244b0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
244c0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
244d0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
244e0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
244f0 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
24500 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
24510 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
24520 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
24530 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
24540 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
24550 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
24560 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
24570 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
24580 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
24590 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
245a0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
245b0 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
245c0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
245d0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
245e0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
245f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24600 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
24610 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
24620 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
24630 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
24640 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24650 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
24660 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
24670 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
24680 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24690 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
246a0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
246b0 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
246c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
246d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
246e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
246f0 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
24700 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
24710 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
24720 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
24730 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24740 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
24750 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
24760 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
24770 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
24780 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24790 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
247a0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
247b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
247c0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
247d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
247e0 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
247f0 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
24800 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
24810 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
24820 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
24830 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
24840 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
24850 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
24860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43  efine SQLITE_REC
24870 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20  URSIVE          
24880 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    33   /* NULL  
24890 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
248a0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a            */../*
248b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
248c0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
248d0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
248e0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
248f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
24900 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63  tines are deprec
24910 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73  ated. Use the [s
24920 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
24930 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
24940 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72  instead of the r
24950 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65  outines describe
24960 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  d here..**.** Th
24970 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
24980 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
24990 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
249a0 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
249b0 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
249c0 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
249d0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
249e0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
249f0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
24a00 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
24a10 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
24a20 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
24a30 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
24a40 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
24a50 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
24a60 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
24a70 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
24a80 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
24a90 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
24aa0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
24ab0 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
24ac0 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
24ad0 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
24ae0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
24af0 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
24b00 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
24b10 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
24b20 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
24b30 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
24b40 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
24b50 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
24b60 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
24b70 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
24b80 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
24b90 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
24ba0 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
24bb0 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
24bc0 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
24bd0 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
24be0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
24bf0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
24c00 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
24c10 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
24c20 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
24c30 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
24c40 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
24c50 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
24c60 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
24c70 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
24c80 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
24c90 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
24ca0 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
24cb0 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
24cc0 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
24cd0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
24ce0 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
24cf0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
24d00 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
24d10 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
24d20 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
24d30 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
24d40 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
24d50 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
24d60 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
24d70 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
24d80 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
24d90 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
24da0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
24db0 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
24dc0 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
24dd0 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
24de0 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
24df0 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
24e00 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
24e10 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
24e20 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
24e30 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
24e40 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
24e50 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
24e60 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
24e70 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
24e80 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
24e90 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
24ea0 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
24eb0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
24ec0 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
24ed0 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
24ee0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
24ef0 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
24f00 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
24f10 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  ED void *sqlite3
24f20 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
24f30 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61 63 65  .   void(*xTrace
24f40 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
24f50 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51  ar*), void*);.SQ
24f60 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
24f70 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
24f80 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
24f90 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
24fa0 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
24fb0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
24fc0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
24fd0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
24fe0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54 72  CAPI3REF: SQL Tr
24ff0 61 63 65 20 45 76 65 6e 74 20 43 6f 64 65 73 0a  ace Event Codes.
25000 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
25010 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a 2a 20  ITE_TRACE.**.** 
25020 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
25030 69 64 65 6e 74 69 66 79 20 63 6c 61 73 73 65 73  identify classes
25040 20 6f 66 20 65 76 65 6e 74 73 20 74 68 61 74 20   of events that 
25050 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72 65 64  can be monitored
25060 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b 73  .** using the [s
25070 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
25080 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67 69 63  )] tracing logic
25090 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
250a0 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c  ument.** to [sql
250b0 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d  ite3_trace_v2()]
250c0 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63 6f 6d   is an OR-ed com
250d0 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e 65 20  bination of one 
250e0 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20 74 68  or more of.** th
250f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 73  e following cons
25100 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66 69 72  tants.  ^The fir
25110 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
25120 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63  he trace callbac
25130 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66 20 74  k.** is one of t
25140 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e  he following con
25150 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 4e 65  stants..**.** Ne
25160 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73 74 61  w tracing consta
25170 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  nts may be added
25180 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
25190 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72  ses..**.** ^A tr
251a0 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68 61 73  ace callback has
251b0 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a   four arguments:
251c0 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50   xCallback(T,C,P
251d0 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61  ,X)..** ^The T a
251e0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
251f0 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 74 79  f the integer ty
25200 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65 2e 0a  pe codes above..
25210 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75 6d 65  ** ^The C argume
25220 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  nt is a copy of 
25230 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e  the context poin
25240 74 65 72 20 70 61 73 73 65 64 20 69 6e 20 61 73  ter passed in as
25250 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 61   the.** fourth a
25260 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
25270 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29 5d 2e  te3_trace_v2()].
25280 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20  .** The P and X 
25290 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f  arguments are po
252a0 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61  inters whose mea
252b0 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20  nings depend on 
252c0 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  T..**.** <dl>.**
252d0 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
252e0 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  STMT]] <dt>SQLIT
252f0 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f 64 74  E_TRACE_STMT</dt
25300 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
25310 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20 63  ITE_TRACE_STMT c
25320 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
25330 65 64 20 77 68 65 6e 20 61 20 70 72 65 70 61 72  ed when a prepar
25340 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
25350 66 69 72 73 74 20 62 65 67 69 6e 73 20 72 75 6e  first begins run
25360 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69 62 6c  ning and possibl
25370 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d 65 73  y at other times
25380 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 65   during the.** e
25390 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
253a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
253b0 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74 20 74  nt, such as at t
253c0 68 65 20 73 74 61 72 74 20 6f 66 20 65 61 63 68  he start of each
253d0 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75 62 70  .** trigger subp
253e0 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50 20 61  rogram. ^The P a
253f0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
25400 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 5b  nter to the.** [
25410 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25420 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72 67 75  nt]. ^The X argu
25430 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
25440 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68  r to a string wh
25450 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 75 6e  ich.** is the un
25460 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74 65 78  expanded SQL tex
25470 74 20 6f 66 20 74 68 65 20 70 72 65 70 61 72 65  t of the prepare
25480 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 20 61  d statement or a
25490 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 0a 2a  n SQL comment .*
254a0 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
254b0 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f 6e 20   the invocation 
254c0 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20 20 5e  of a trigger.  ^
254d0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 61 6e  The callback can
254e0 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68 65 20   compute.** the 
254f0 73 61 6d 65 20 74 65 78 74 20 74 68 61 74 20 77  same text that w
25500 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e 20 72  ould have been r
25510 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 6c  eturned by the l
25520 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 74  egacy [sqlite3_t
25530 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  race()].** inter
25540 66 61 63 65 20 62 79 20 75 73 69 6e 67 20 74 68  face by using th
25550 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77 68 65  e X argument whe
25560 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74 68 20  n X begins with 
25570 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  "--" and invokin
25580 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  g.** [sqlite3_ex
25590 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d 20 6f  panded_sql(P)] o
255a0 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
255b0 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  [[SQLITE_TRACE_P
255c0 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53 51 4c  ROFILE]] <dt>SQL
255d0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
255e0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  E</dt>.** <dd>^A
255f0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50  n SQLITE_TRACE_P
25600 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20  ROFILE callback 
25610 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f 78 69  provides approxi
25620 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d 65 0a  mately the same.
25630 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ** information a
25640 73 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  s is provided by
25650 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
25660 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62 61 63  ofile()] callbac
25670 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67  k..** ^The P arg
25680 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
25690 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  er to the [prepa
256a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
256b0 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75  nd the.** X argu
256c0 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61  ment points to a
256d0 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20   64-bit integer 
256e0 77 68 69 63 68 20 69 73 20 74 68 65 20 65 73 74  which is the est
256f0 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74 68 65  imated of.** the
25700 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e 6f 73   number of nanos
25710 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65 20 70  econd that the p
25720 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25730 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 0a 2a  t took to run..*
25740 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 54 52  * ^The SQLITE_TR
25750 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c  ACE_PROFILE call
25760 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
25770 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  when the stateme
25780 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a 2a 0a  nt finishes..**.
25790 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
257a0 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51 4c 49  E_ROW]] <dt>SQLI
257b0 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f 64 74  TE_TRACE_ROW</dt
257c0 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c  >.** <dd>^An SQL
257d0 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20 63 61  ITE_TRACE_ROW ca
257e0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
257f0 64 20 77 68 65 6e 65 76 65 72 20 61 20 70 72 65  d whenever a pre
25800 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
25810 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61 20 73  nt generates a s
25820 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72 65 73  ingle row of res
25830 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65 20 50  ult.  .** ^The P
25840 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
25850 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70  ointer to the [p
25860 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
25870 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20  t] and the.** X 
25880 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
25890 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  ed..**.** [[SQLI
258a0 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 5d 5d  TE_TRACE_CLOSE]]
258b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
258c0 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20  E_CLOSE</dt>.** 
258d0 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54  <dd>^An SQLITE_T
258e0 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c 6c 62  RACE_CLOSE callb
258f0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
25900 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hen a database.*
25910 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  * connection clo
25920 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61  ses..** ^The P a
25930 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
25940 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
25950 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25960 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  ] object.** and 
25970 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  the X argument i
25980 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c 2f 64  s unused..** </d
25990 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
259a0 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 20  LITE_TRACE_STMT 
259b0 20 20 20 20 20 20 30 78 30 31 0a 23 64 65 66 69        0x01.#defi
259c0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  ne SQLITE_TRACE_
259d0 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30 32 0a  PROFILE    0x02.
259e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
259f0 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20 20 20  RACE_ROW        
25a00 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x04.#define SQL
25a10 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20  ITE_TRACE_CLOSE 
25a20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a 2a 2a       0x08../*.**
25a30 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 54   CAPI3REF: SQL T
25a40 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d 45 54  race Hook.** MET
25a50 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
25a60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
25a70 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58 2c 50  trace_v2(D,M,X,P
25a80 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
25a90 73 74 65 72 73 20 61 20 74 72 61 63 65 20 63 61  sters a trace ca
25aa0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
25ab0 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b 64 61  on X against [da
25ac0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25ad0 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72 6f 70  n] D, using prop
25ae0 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a 20 61  erty mask M.** a
25af0 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74  nd context point
25b00 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65 20 58  er P.  ^If the X
25b10 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a 2a 20   callback is.** 
25b20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65 20 4d  NULL or if the M
25b30 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c 20 74   mask is zero, t
25b40 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73 20 64  hen tracing is d
25b50 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a 2a 2a  isabled.  The.**
25b60 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75   M argument shou
25b70 6c 64 20 62 65 20 74 68 65 20 62 69 74 77 69 73  ld be the bitwis
25b80 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74  e OR-ed combinat
25b90 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f 20 6f  ion of.** zero o
25ba0 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45 5f 54  r more [SQLITE_T
25bb0 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74 73 2e  RACE] constants.
25bc0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63 61 6c  .**.** ^Each cal
25bd0 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71 6c 69  l to either sqli
25be0 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20 73  te3_trace() or s
25bf0 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
25c00 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a 2a 20  ) overrides .** 
25c10 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20 70 72  (cancels) any pr
25c20 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ior calls to sql
25c30 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72 20  ite3_trace() or 
25c40 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32  sqlite3_trace_v2
25c50 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 58  ()..**.** ^The X
25c60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
25c70 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e  oked whenever an
25c80 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74 73 20  y of the events 
25c90 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 0a 2a  identified by .*
25ca0 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72 2e 20  * mask M occur. 
25cb0 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20 72 65   ^The integer re
25cc0 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
25cd0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
25ce0 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69 67 6e  currently.** ign
25cf0 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74 68 69  ored, though thi
25d00 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69 6e 20  s may change in 
25d10 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
25d20 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 6d    Callback.** im
25d30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68  plementations sh
25d40 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65 72 6f  ould return zero
25d50 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74 75 72   to ensure futur
25d60 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  e compatibility.
25d70 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20  .**.** ^A trace 
25d80 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
25d90 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20 61 72  ked with four ar
25da0 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62 61 63  guments: callbac
25db0 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e  k(T,C,P,X)..** ^
25dc0 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69  The T argument i
25dd0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 53 51  s one of the [SQ
25de0 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a 20 63  LITE_TRACE].** c
25df0 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e 64 69  onstants to indi
25e00 63 61 74 65 20 77 68 79 20 74 68 65 20 63 61 6c  cate why the cal
25e10 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f 6b 65  lback was invoke
25e20 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67  d..** ^The C arg
25e30 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20  ument is a copy 
25e40 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70  of the context p
25e50 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65 20 50  ointer..** The P
25e60 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73   and X arguments
25e70 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68   are pointers wh
25e80 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70  ose meanings dep
25e90 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20  end on T..**.** 
25ea0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
25eb0 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  e_v2() interface
25ec0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
25ed0 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65 67 61  replace the lega
25ee0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  cy.** interfaces
25ef0 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   [sqlite3_trace(
25f00 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
25f10 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f 74 68  profile()], both
25f20 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61 72 65   of which.** are
25f30 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a 2f 0a   deprecated..*/.
25f40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
25f50 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
25f60 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75  .  sqlite3*,.  u
25f70 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20  nsigned uMask,. 
25f80 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29   int(*xCallback)
25f90 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c  (unsigned,void*,
25fa0 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20  void*,void*),.  
25fb0 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f  void *pCtx.);../
25fc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
25fd0 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
25fe0 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
25ff0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
26000 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72   ^The sqlite3_pr
26010 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44  ogress_handler(D
26020 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,N,X,P) interfac
26030 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
26040 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
26050 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n X to be invoke
26060 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
26070 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
26080 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ng calls to.** [
26090 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
260a0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
260b0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67  ] and [sqlite3_g
260c0 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a  et_table()] for.
260d0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
260e0 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78  ection D.  An ex
260f0 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
26100 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
26110 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
26120 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
26130 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
26140 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65  *.** ^The parame
26150 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20  ter P is passed 
26160 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f  through as the o
26170 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
26180 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63   the .** callbac
26190 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e  k function X.  ^
261a0 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  The parameter N 
261b0 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61  is the approxima
261c0 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  te number of .**
261d0 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e   [virtual machin
261e0 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20  e instructions] 
261f0 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74  that are evaluat
26200 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65  ed between succe
26210 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  ssive.** invocat
26220 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c  ions of the call
26230 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69  back X.  ^If N i
26240 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20  s less than one 
26250 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73  then the progres
26260 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20  s.** handler is 
26270 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
26280 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70  ^Only a single p
26290 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
262a0 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61  may be defined a
262b0 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a  t one time per.*
262c0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
262d0 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67  ection]; setting
262e0 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20   a new progress 
262f0 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20  handler cancels 
26300 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20  the.** old one. 
26310 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65   ^Setting parame
26320 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69  ter X to NULL di
26330 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72  sables the progr
26340 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
26350 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61  ^The progress ha
26360 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69  ndler is also di
26370 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e  sabled by settin
26380 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c  g N to a value l
26390 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a  ess.** than 1..*
263a0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
263b0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
263c0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
263d0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
263e0 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
263f0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
26400 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
26410 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
26420 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
26430 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
26440 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
26450 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
26460 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
26470 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
26480 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
26490 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
264a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
264b0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
264c0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
264d0 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
264e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
264f0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
26500 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
26510 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
26520 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
26530 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
26540 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
26550 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
26560 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49  raph..**.*/.SQLI
26570 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
26580 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
26590 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
265a0 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  nt, int(*)(void*
265b0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
265c0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
265d0 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61  ing A New Databa
265e0 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se Connection.**
265f0 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20 73 71   CONSTRUCTOR: sq
26600 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
26610 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
26620 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
26630 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
26640 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
26650 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
26660 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
26670 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
26680 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
26690 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
266a0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
266b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
266c0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
266d0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
266e0 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
266f0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
26700 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
26710 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
26720 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
26730 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
26740 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
26750 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
26760 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
26770 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
26780 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
26790 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
267a0 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
267b0 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
267c0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
267d0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
267e0 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
267f0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
26800 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
26810 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
26820 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
26830 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
26840 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
26850 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
26860 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
26870 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
26880 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
26890 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
268a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
268b0 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
268c0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
268d0 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
268e0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
268f0 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
26900 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
26910 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
26920 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
26930 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
26940 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
26950 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
26960 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
26970 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62 65 20  ncoding will be 
26980 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61 62 61  UTF-8 for databa
26990 73 65 73 20 63 72 65 61 74 65 64 20 75 73 69 6e  ses created usin
269a0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  g.** sqlite3_ope
269b0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
269c0 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68 65 20  pen_v2().  ^The 
269d0 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67  default encoding
269e0 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 0a 2a   for databases.*
269f0 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  * created using 
26a00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
26a10 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31 36 20   will be UTF-16 
26a20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
26a30 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20  te order..**.** 
26a40 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
26a50 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
26a60 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
26a70 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
26a80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
26a90 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
26aa0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
26ab0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
26ac0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
26ad0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
26ae0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
26af0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
26b00 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
26b10 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
26b20 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
26b30 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
26b40 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
26b50 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
26b60 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
26b70 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
26b80 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
26b90 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
26ba0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
26bb0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
26bc0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
26bd0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
26be0 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
26bf0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
26c00 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
26c10 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
26c20 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
26c30 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
26c40 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
26c50 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
26c60 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
26c70 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
26c80 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
26c90 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c  N_PRIVATECACHE],
26ca0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
26cb0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a  OPEN_URI] flags:
26cc0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
26cd0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
26ce0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
26cf0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
26d00 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
26d10 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
26d20 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
26d30 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
26d40 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
26d50 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
26d60 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
26d70 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
26d80 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
26d90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26da0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
26db0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
26dc0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
26dd0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
26de0 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
26df0 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
26e00 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
26e10 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
26e20 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
26e30 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
26e40 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
26e50 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
26e60 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
26e70 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
26e80 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
26e90 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
26ea0 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
26eb0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
26ec0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
26ed0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
26ee0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
26ef0 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
26f00 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f  ated if.** it do
26f10 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
26f20 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
26f30 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
26f40 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
26f50 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
26f60 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
26f70 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
26f80 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
26f90 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
26fa0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
26fb0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
26fc0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
26fd0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
26fe0 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61  wn above optiona
26ff0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
27000 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49  h other.** [SQLI
27010 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
27020 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a   | SQLITE_OPEN_*
27030 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74   bits].** then t
27040 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
27050 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
27060 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
27070 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
27080 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
27090 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
270a0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
270b0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
270c0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
270d0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
270e0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
270f0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
27100 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
27110 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
27120 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
27130 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
27140 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
27150 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
27160 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
27170 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
27180 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
27190 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
271a0 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
271b0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
271c0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
271d0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
271e0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
271f0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
27200 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
27210 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
27220 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
27230 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
27240 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
27250 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
27260 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
27270 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
27280 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
27290 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
272a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
272b0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
272c0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
272d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
272e0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
272f0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
27300 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
27310 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
27320 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
27330 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
27340 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
27350 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
27360 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
27370 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
27380 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
27390 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
273a0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
273b0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
273c0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
273d0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
273e0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
273f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
27400 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
27410 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
27420 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
27430 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
27440 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
27450 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
27460 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
27470 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
27480 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
27490 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
274a0 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
274b0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
274c0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
274d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
274e0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
274f0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
27500 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
27510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
27520 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
27530 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
27540 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
27550 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
27560 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
27570 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
27580 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
27590 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
275a0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
275b0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
275c0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
275d0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
275e0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
275f0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
27600 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
27610 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
27620 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
27630 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
27640 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
27650 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
27660 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
27670 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
27680 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
27690 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
276a0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
276b0 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
276c0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
276d0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
276e0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
276f0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
27700 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
27710 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
27720 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
27730 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65  enames in sqlite
27740 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55  3_open()]] <h3>U
27750 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33  RI Filenames</h3
27760 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49  >.**.** ^If [URI
27770 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72   filename] inter
27780 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
27790 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69  bled, and the fi
277a0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
277b0 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22  ** begins with "
277c0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65  file:", then the
277d0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74   filename is int
277e0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52  erpreted as a UR
277f0 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e  I. ^URI.** filen
27800 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
27810 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  on is enabled if
27820 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
27830 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a  N_URI] flag is.*
27840 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75  * set in the fou
27850 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
27860 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
27870 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
27880 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
27890 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
278a0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
278b0 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
278c0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
278d0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
278e0 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
278f0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
27900 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
27910 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c  on..** As of SQL
27920 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
27930 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  7, URI filename 
27940 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
27950 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
27960 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
27970 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
27980 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
27990 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
279a0 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
279b0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
279c0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
279d0 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
279e0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
279f0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
27a00 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
27a10 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
27a20 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
27a30 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
27a40 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
27a50 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
27a60 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
27a70 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
27a80 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
27a90 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
27aa0 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
27ab0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
27ac0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
27ad0 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
27ae0 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
27af0 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
27b00 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
27b10 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
27b20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
27b30 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
27b40 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
27b50 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
27b60 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
27b70 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
27b80 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
27b90 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
27ba0 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
27bb0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
27bc0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
27bd0 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
27be0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
27bf0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
27c00 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
27c10 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
27c20 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
27c30 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
27c40 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
27c50 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
27c60 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
27c70 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
27c80 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
27c90 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
27ca0 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74   ^(On windows, t
27cb0 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65  he first compone
27cc0 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74  nt of an absolut
27cd0 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20  e path .** is a 
27ce0 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74  drive specificat
27cf0 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e  ion (e.g. "C:").
27d00 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20  )^.**.** [[core 
27d10 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65  URI query parame
27d20 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75  ters]].** The qu
27d30 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
27d40 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61   a URI may conta
27d50 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  in parameters th
27d60 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  at are interpret
27d70 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20  ed.** either by 
27d80 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f  SQLite itself, o
27d90 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75  r by a [VFS | cu
27da0 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
27db0 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
27dc0 69 74 65 20 61 6e 64 20 69 74 73 20 62 75 69 6c  ite and its buil
27dd0 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69 6e 74  t-in [VFSes] int
27de0 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20 66 6f  erpret the.** fo
27df0 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20 70 61  llowing query pa
27e00 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
27e10 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
27e20 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
27e30 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
27e40 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
27e50 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
27e60 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
27e70 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
27e80 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
27e90 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
27ea0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
27eb0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
27ec0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
27ed0 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
27ee0 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
27ef0 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
27f00 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
27f10 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
27f20 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
27f30 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
27f40 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
27f50 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
27f60 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
27f70 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
27f80 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
27f90 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
27fa0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
27fb0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
27fc0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
27fd0 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
27fe0 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
27ff0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
28000 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
28010 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
28020 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
28030 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
28040 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
28050 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
28060 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
28070 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
28080 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
28090 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
280a0 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
280b0 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
280c0 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
280d0 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
280e0 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
280f0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
28100 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
28110 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
28120 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
28130 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
28140 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
28150 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
28160 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
28170 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
28180 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
28190 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
281a0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
281b0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
281c0 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
281d0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
281e0 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
281f0 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
28200 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
28210 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
28220 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
28230 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
28240 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
28250 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
28260 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
28270 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
28280 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
28290 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
282a0 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
282b0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20  E_OPEN_CREATE.  
282c0 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
282d0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65  ion is.**     se
282e0 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68  t to "memory" th
282f0 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65  en a pure [in-me
28300 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74  mory database] t
28310 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a  hat never reads.
28320 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73  **     or writes
28330 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73   from disk is us
28340 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72  ed. ^It is an er
28350 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
28360 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20   value for.**   
28370 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d    the mode param
28380 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73  eter that is les
28390 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
283a0 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
283b0 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20  d by.**     the 
283c0 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20  flags passed in 
283d0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
283e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
283f0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
28400 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
28410 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
28420 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
28430 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
28440 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
28450 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
28460 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
28470 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
28480 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
28490 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
284a0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
284b0 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
284c0 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
284d0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
284e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
284f0 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
28500 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
28510 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
28520 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
28530 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
28540 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
28550 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
28560 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
28570 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
28580 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
28590 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
285a0 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
285b0 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
285c0 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
285d0 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72  des any behavior
285e0 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65   requested by se
285f0 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c  tting.**     SQL
28600 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
28610 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f  CACHE or SQLITE_
28620 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
28630 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c   flag..**.**  <l
28640 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20  i> <b>psow</b>: 
28650 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65  ^The psow parame
28660 74 65 72 20 69 6e 64 69 63 61 74 65 73 20 77 68  ter indicates wh
28670 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
28680 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72 73 61  .**     [powersa
28690 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20 70 72  fe overwrite] pr
286a0 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72 20 64  operty does or d
286b0 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20 74 6f  oes not apply to
286c0 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74 6f 72   the.**     stor
286d0 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77 68 69  age media on whi
286e0 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ch the database 
286f0 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a 2a 2a  file resides..**
28700 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c  .**  <li> <b>nol
28710 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f  ock</b>: ^The no
28720 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69  lock parameter i
28730 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72  s a boolean quer
28740 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20  y parameter.**  
28750 20 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20     which if set 
28760 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f  disables file lo
28770 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63  cking in rollbac
28780 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e  k journal modes.
28790 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73    This.**     is
287a0 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65   useful for acce
287b0 73 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65  ssing a database
287c0 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d   on a filesystem
287d0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a   that does not.*
287e0 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f  *     support lo
287f0 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a  cking.  Caution:
28800 20 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75    Database corru
28810 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75  ption might resu
28820 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20  lt if two.**    
28830 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73   or more process
28840 65 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20  es write to the 
28850 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e  same database an
28860 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f  d any one of tho
28870 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73  se.**     proces
28880 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d  ses uses nolock=
28890 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  1..**.**  <li> <
288a0 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a  b>immutable</b>:
288b0 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20   ^The immutable 
288c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
288d0 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20  oolean query.** 
288e0 20 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68      parameter th
288f0 61 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  at indicates tha
28900 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  t the database f
28910 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e  ile is stored on
28920 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c  .**     read-onl
28930 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20  y media.  ^When 
28940 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74  immutable is set
28950 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  , SQLite assumes
28960 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
28970 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63   database file c
28980 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64  annot be changed
28990 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63  , even by a proc
289a0 65 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a  ess with higher.
289b0 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65  **     privilege
289c0 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74  , and so the dat
289d0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
289e0 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c  read-only and al
289f0 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20  l locking.**    
28a00 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65   and change dete
28a10 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65  ction is disable
28a20 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74  d.  Caution: Set
28a30 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62  ting the immutab
28a40 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72  le.**     proper
28a50 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ty on a database
28a60 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20   file that does 
28a70 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63  in fact change c
28a80 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20  an result.**    
28a90 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75   in incorrect qu
28aa0 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f  ery results and/
28ab0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  or [SQLITE_CORRU
28ac0 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20  PT] errors..**  
28ad0 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51     See also: [SQ
28ae0 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
28af0 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20  ABLE]..**       
28b00 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
28b10 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
28b20 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72  nknown parameter
28b30 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f   in the query co
28b40 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
28b50 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72   is not an.** er
28b60 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72  ror.  Future ver
28b70 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
28b80 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64  might understand
28b90 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72   additional quer
28ba0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  y.** parameters.
28bb0 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61    See "[query pa
28bc0 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70  rameters with sp
28bd0 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f  ecial meaning to
28be0 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a   SQLite]" for.**
28bf0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
28c00 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  rmation..**.** [
28c10 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  [URI filename ex
28c20 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49  amples]] <h3>URI
28c30 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
28c40 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74  es</h3>.**.** <t
28c50 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20  able border="1" 
28c60 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c  align=center cel
28c70 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c  lpadding=5>.** <
28c80 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65  tr><th> URI file
28c90 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c  names <th> Resul
28ca0 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  ts.** <tr><td> f
28cb0 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e  ile:data.db <td>
28cc0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
28cd0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
28ce0 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
28cf0 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a  rent directory..
28d00 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
28d10 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
28d20 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20  .db<br>.**      
28d30 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65      file:///home
28d40 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
28d50 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r> .**          
28d60 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74  file://localhost
28d70 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
28d80 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a  db <br> <td> .**
28d90 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
28da0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
28db0 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
28dc0 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  a.db"..** <tr><t
28dd0 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74  d> file://darkst
28de0 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ar/home/fred/dat
28df0 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
28e00 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
28e10 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e   "darkstar" is n
28e20 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20  ot a recognized 
28e30 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74  authority..** <t
28e40 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69  r><td style="whi
28e50 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22  te-space:nowrap"
28e60 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
28e70 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65  ile:///C:/Docume
28e80 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74  nts%20and%20Sett
28e90 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f  ings/fred/Deskto
28ea0 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20  p/data.db.**    
28eb0 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e   <td> Windows on
28ec0 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c  ly: Open the fil
28ed0 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66  e "data.db" on f
28ee0 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e  red's desktop on
28ef0 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20   drive.**       
28f00 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74     C:. Note that
28f10 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e   the %20 escapin
28f20 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c  g in this exampl
28f30 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c  e is not strictl
28f40 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  y .**          n
28f50 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65  ecessary - space
28f60 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20   characters can 
28f70 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c  be used literall
28f80 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  y.**          in
28f90 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a   URI filenames..
28fa0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
28fb0 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f  :data.db?mode=ro
28fc0 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c  &cache=private <
28fd0 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
28fe0 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61   Open file "data
28ff0 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
29000 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f  ent directory fo
29010 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65  r read-only acce
29020 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss..**          
29030 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
29040 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
29050 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69  red-cache mode i
29060 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20  s enabled by.** 
29070 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74           default
29080 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20  , use a private 
29090 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cache..** <tr><t
290a0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
290b0 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75  ed/data.db?vfs=u
290c0 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e  nix-dotfile <td>
290d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
290e0 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  n file "/home/fr
290f0 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65  ed/data.db". Use
29100 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53   the special VFS
29110 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a   "unix-dotfile".
29120 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74  **          that
29130 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20   uses dot-files 
29140 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69  in place of posi
29150 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69  x advisory locki
29160 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ng..** <tr><td> 
29170 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
29180 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20  e=readonly <td> 
29190 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
291a0 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79  error. "readonly
291b0 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64  " is not a valid
291c0 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20   option for the 
291d0 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72  "mode" parameter
291e0 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ..** </table>.**
291f0 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63  .** ^URI hexadec
29200 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
29210 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20  ences (%HH) are 
29220 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
29230 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a   the path and.**
29240 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
29250 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65  s of a URI. A he
29260 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
29270 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73   sequence consis
29280 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65  ts of a.** perce
29290 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20  nt sign - "%" - 
292a0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63  followed by exac
292b0 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69  tly two hexadeci
292c0 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73  mal digits .** s
292d0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74  pecifying an oct
292e0 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72  et value. ^Befor
292f0 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75  e the path or qu
29300 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
29310 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  f a.** URI filen
29320 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65  ame are interpre
29330 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e  ted, they are en
29340 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
29350 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65  8 and all .** he
29360 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
29370 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61   sequences repla
29380 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ced by a single 
29390 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  byte containing 
293a0 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
293b0 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74  ding octet. If t
293c0 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65  his process gene
293d0 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64  rates an invalid
293e0 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c   UTF-8 encoding,
293f0 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20  .** the results 
29400 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
29410 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
29420 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
29430 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
29440 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
29450 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
29460 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
29470 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
29480 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
29490 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
294a0 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
294b0 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
294c0 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
294d0 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
294e0 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
294f0 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
29500 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
29510 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
29520 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
29530 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
29540 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
29550 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c  en_v2()..**.** <
29560 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
29570 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a  s Runtime users:
29580 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72  </b>  The tempor
29590 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75  ary directory mu
295a0 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69  st be set.** pri
295b0 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71  or to calling sq
295c0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
295d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
295e0 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76  ).  Otherwise, v
295f0 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72  arious.** featur
29600 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20  es that require 
29610 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f  the use of tempo
29620 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66  rary files may f
29630 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ail..**.** See a
29640 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65  lso: [sqlite3_te
29650 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f  mp_directory].*/
29660 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29670 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
29680 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
29690 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
296a0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
296b0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
296c0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
296d0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
296e0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
296f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29700 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
29710 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
29720 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
29730 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
29740 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
29750 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
29760 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
29770 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
29780 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
29790 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
297a0 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
297b0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
297c0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
297d0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
297e0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
297f0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
29800 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
29810 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
29820 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
29830 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
29840 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
29850 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
29860 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
29870 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
29880 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
29890 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
298a0 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
298b0 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79  hese are utility
298c0 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75   routines, usefu
298d0 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65  l to VFS impleme
298e0 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63  ntations, that c
298f0 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69  heck.** to see i
29900 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
29910 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
29920 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
29930 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
29940 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
29950 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
29960 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71   value of that q
29970 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  uery parameter..
29980 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68  **.** If F is th
29990 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  e database filen
299a0 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ame pointer pass
299b0 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
299c0 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a  n() method of .*
299d0 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  * a VFS implemen
299e0 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  tation when the 
299f0 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
29a00 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f  to xOpen() has o
29a10 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f  ne or .** more o
29a20 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
29a30 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49  EN_URI] or [SQLI
29a40 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
29a50 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a   bits set and.**
29a60 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f   P is the name o
29a70 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
29a80 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73  meter, then.** s
29a90 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
29aa0 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
29ab0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
29ac0 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65  he P.** paramete
29ad0 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f  r if it exists o
29ae0 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
29af0 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61   if P does not a
29b00 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71  ppear as a .** q
29b10 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
29b20 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20  n F.  If P is a 
29b30 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
29b40 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65  of F.** has no e
29b50 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74  xplicit value, t
29b60 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
29b70 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
29b80 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e  eturns.** a poin
29b90 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ter to an empty 
29ba0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
29bb0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
29bc0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
29bd0 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61  tine assumes tha
29be0 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  t P is a boolean
29bf0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e  .** parameter an
29c00 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  d returns true (
29c10 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20  1) or false (0) 
29c20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
29c30 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20   value.** of P. 
29c40 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
29c50 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
29c60 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
29c70 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a  true (1) if the.
29c80 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72  ** value of quer
29c90 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
29ca0 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22   one of "yes", "
29cb0 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69  true", or "on" i
29cc0 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72  n any.** case or
29cd0 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
29ce0 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d  gins with a non-
29cf0 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68  zero number.  Th
29d00 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  e .** sqlite3_ur
29d10 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
29d20 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
29d30 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74  s false (0) if t
29d40 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71  he value of.** q
29d50 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
29d60 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c   is one of "no",
29d70 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66   "false", or "of
29d80 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f  f" in any case o
29d90 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75  r.** if the valu
29da0 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
29db0 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49  numeric zero.  I
29dc0 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65  f P is not a que
29dd0 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ry.** parameter 
29de0 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76  on F or if the v
29df0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65  alue of P is doe
29e00 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20  s not match any 
29e10 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c  of the.** above,
29e20 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
29e30 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
29e40 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e   returns (B!=0).
29e50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
29e60 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50  e3_uri_int64(F,P
29e70 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76  ,D) routine conv
29e80 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f  erts the value o
29e90 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34  f P into a.** 64
29ea0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
29eb0 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ger and returns 
29ec0 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72  that integer, or
29ed0 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74   D if P does not
29ee0 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74  .** exist.  If t
29ef0 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
29f00 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
29f10 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72   than an integer
29f20 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69  , then.** zero i
29f30 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a  s returned..** .
29f40 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c  ** If F is a NUL
29f50 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
29f60 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
29f70 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
29f80 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73  ns NULL and.** s
29f90 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
29fa0 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
29fb0 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f  s B.  If F is no
29fc0 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  t a NULL pointer
29fd0 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61   and.** is not a
29fe0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70   database file p
29ff0 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  athname pointer 
2a000 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73  that SQLite pass
2a010 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
2a020 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c  n.** VFS method,
2a030 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2a040 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  or of this routi
2a050 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ne is undefined 
2a060 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20  and probably.** 
2a070 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a  undesirable..*/.
2a080 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2a090 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75   char *sqlite3_u
2a0a0 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
2a0b0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
2a0c0 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
2a0d0 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f  zParam);.SQLITE_
2a0e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2a0f0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
2a100 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
2a110 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
2a120 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
2a130 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
2a140 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
2a150 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
2a160 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
2a170 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
2a180 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
2a190 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
2a1a0 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
2a1b0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
2a1c0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ite3.**.** ^If t
2a1d0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
2a1e0 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
2a1f0 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
2a200 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  h .** [database 
2a210 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61  connection] D fa
2a220 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73  iled, then the s
2a230 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
2a240 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
2a250 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
2a260 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
2a270 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65   or [extended re
2a280 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
2a290 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e  hat.** API call.
2a2a0 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20  .** If the most 
2a2b0 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
2a2c0 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a  was successful,.
2a2d0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
2a2e0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
2a2f0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
2a300 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2a310 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
2a320 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
2a330 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
2a340 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
2a350 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
2a360 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
2a370 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
2a380 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
2a390 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
2a3a0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
2a3b0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
2a3c0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
2a3d0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
2a3e0 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
2a3f0 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
2a400 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
2a410 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
2a420 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
2a430 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
2a440 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
2a450 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
2a460 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
2a470 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
2a480 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
2a490 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2a4a0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
2a4b0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
2a4c0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
2a4d0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
2a4e0 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
2a4f0 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
2a500 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
2a510 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
2a520 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
2a530 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
2a540 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
2a550 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
2a560 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
2a570 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2a580 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
2a590 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
2a5a0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
2a5b0 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
2a5c0 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
2a5d0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
2a5e0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
2a5f0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
2a600 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
2a610 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
2a620 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
2a630 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
2a640 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
2a650 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
2a660 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
2a670 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
2a680 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
2a690 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
2a6a0 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
2a6b0 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
2a6c0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
2a6d0 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
2a6e0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
2a6f0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
2a700 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
2a710 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
2a720 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
2a730 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
2a740 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
2a750 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
2a760 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
2a770 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
2a780 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
2a790 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
2a7a0 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
2a7b0 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
2a7c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2a7d0 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
2a7e0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
2a7f0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
2a800 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
2a810 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
2a820 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
2a830 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
2a840 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
2a850 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
2a860 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
2a870 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
2a880 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
2a890 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
2a8a0 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
2a8b0 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
2a8c0 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
2a8d0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
2a8e0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
2a8f0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
2a900 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
2a910 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
2a920 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
2a930 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
2a940 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
2a950 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
2a960 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  set..*/.SQLITE_A
2a970 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
2a980 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
2a990 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  db);.SQLITE_API 
2a9a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
2a9b0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
2a9c0 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54  ite3 *db);.SQLIT
2a9d0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2a9e0 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
2a9f0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
2aa00 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2aa10 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
2aa20 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53  g16(sqlite3*);.S
2aa30 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2aa40 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
2aa50 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  rstr(int);../*.*
2aa60 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65 70  * CAPI3REF: Prep
2aa70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2aa80 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
2aa90 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
2aaa0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
2aab0 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
2aac0 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
2aad0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
2aae0 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
2aaf0 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
2ab00 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65 65   that.** has bee
2ab10 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  n compiled into 
2ab20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64 20  binary form and 
2ab30 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20 65  is ready to be e
2ab40 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  valuated..**.** 
2ab50 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53 51  Think of each SQ
2ab60 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 61  L statement as a
2ab70 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75 74   separate comput
2ab80 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68 65  er program.  The
2ab90 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
2aba0 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65 20   text is source 
2abb0 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72 65  code.  A prepare
2abc0 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65  d statement obje
2abd0 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63 6f  ct .** is the co
2abe0 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63 6f  mpiled object co
2abf0 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75 73  de.  All SQL mus
2ac00 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 69  t be converted i
2ac10 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72 65  nto a.** prepare
2ac20 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66 6f  d statement befo
2ac30 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75 6e  re it can be run
2ac40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65  ..**.** The life
2ac50 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65 70  -cycle of a prep
2ac60 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
2ac70 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67 6f  bject usually go
2ac80 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  es like this:.**
2ac90 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
2aca0 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65 70   Create the prep
2acb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f  ared statement o
2acc0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
2acd0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2ace0 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  )]..** <li> Bind
2acf0 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72 61   values to [para
2ad00 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68  meters] using th
2ad10 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2ad20 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72  ().**      inter
2ad30 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  faces..** <li> R
2ad40 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63 61  un the SQL by ca
2ad50 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  lling [sqlite3_s
2ad60 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f  tep()] one or mo
2ad70 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69  re times..** <li
2ad80 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65 70  > Reset the prep
2ad90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
2ada0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
2adb0 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
2adc0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
2add0 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
2ade0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
2adf0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
2ae00 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
2ae10 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
2ae20 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
2ae30 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ol>.*/.typedef s
2ae40 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
2ae50 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
2ae60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ae70 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
2ae80 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
2ae90 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ite3.**.** ^(Thi
2aea0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
2aeb0 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76  ws the size of v
2aec0 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74  arious construct
2aed0 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a  s to be limited.
2aee0 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69  ** on a connecti
2aef0 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e  on by connection
2af00 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69 72   basis.  The fir
2af10 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2af20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
2af30 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f   connection] who
2af40 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62  se limit is to b
2af50 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65 64  e set or queried
2af60 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
2af70 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e   parameter is on
2af80 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20  e of the [limit 
2af90 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74  categories] that
2afa0 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61   define a.** cla
2afb0 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73  ss of constructs
2afc0 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69   to be size limi
2afd0 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64 20  ted.  The third 
2afe0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2aff0 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f  .** new limit fo
2b000 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74  r that construct
2b010 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  .)^.**.** ^If th
2b020 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61  e new limit is a
2b030 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
2b040 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75  , the limit is u
2b050 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46  nchanged..** ^(F
2b060 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61  or each limit ca
2b070 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49  tegory SQLITE_LI
2b080 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20  MIT_<i>NAME</i> 
2b090 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b  there is a .** [
2b0a0 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70  limits | hard up
2b0b0 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65  per bound].** se
2b0c0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
2b0d0 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f 63  e by a C preproc
2b0e0 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c  essor macro call
2b0f0 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  ed.** [limits | 
2b100 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41  SQLITE_MAX_<i>NA
2b110 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65  ME</i>]..** (The
2b120 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68   "_LIMIT_" in th
2b130 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65  e name is change
2b140 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e  d to "_MAX_".))^
2b150 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f  .** ^Attempts to
2b160 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69   increase a limi
2b170 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72 64  t above its hard
2b180 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65   upper bound are
2b190 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75  .** silently tru
2b1a0 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68 61  ncated to the ha
2b1b0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a  rd upper bound..
2b1c0 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73  **.** ^Regardles
2b1d0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
2b1e0 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61  not the limit wa
2b1f0 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a  s changed, the .
2b200 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ** [sqlite3_limi
2b210 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  t()] interface r
2b220 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72  eturns the prior
2b230 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69   value of the li
2b240 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20  mit..** ^Hence, 
2b250 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72 72  to find the curr
2b260 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c  ent value of a l
2b270 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68 61  imit without cha
2b280 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d  nging it,.** sim
2b290 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20  ply invoke this 
2b2a0 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20 74  interface with t
2b2b0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2b2c0 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a  er set to -1..**
2b2d0 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d  .** Run-time lim
2b2e0 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  its are intended
2b2f0 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c   for use in appl
2b300 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61  ications that ma
2b310 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65  nage.** both the
2b320 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20  ir own internal 
2b330 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73  database and als
2b340 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61 74  o databases that
2b350 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a   are controlled.
2b360 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64 20  ** by untrusted 
2b370 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
2b380 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70  .  An example ap
2b390 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20  plication might 
2b3a0 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77  be a.** web brow
2b3b0 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74 73  ser that has its
2b3c0 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20 66   own databases f
2b3d0 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f  or storing histo
2b3e0 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61  ry and.** separa
2b3f0 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e  te databases con
2b400 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53  trolled by JavaS
2b410 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f  cript applicatio
2b420 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a  ns downloaded.**
2b430 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65   off the Interne
2b440 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c  t.  The internal
2b450 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20 62   databases can b
2b460 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c  e given the.** l
2b470 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69  arge, default li
2b480 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65 73  mits.  Databases
2b490 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74 65   managed by exte
2b4a0 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e  rnal sources can
2b4b0 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63  .** be given muc
2b4c0 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73  h smaller limits
2b4d0 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65   designed to pre
2b4e0 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66  vent a denial of
2b4f0 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61   service.** atta
2b500 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20  ck.  Developers 
2b510 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20  might also want 
2b520 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69  to use the [sqli
2b530 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
2b540 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  er()].** interfa
2b550 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f  ce to further co
2b560 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20  ntrol untrusted 
2b570 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  SQL.  The size o
2b580 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
2b590 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e 20  * created by an 
2b5a0 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70 74  untrusted script
2b5b0 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65   can be containe
2b5c0 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  d using the.** [
2b5d0 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20  max_page_count] 
2b5e0 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20  [PRAGMA]..**.** 
2b5f0 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d  New run-time lim
2b600 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61  it categories ma
2b610 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
2b620 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
2b630 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2b640 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
2b650 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
2b660 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
2b670 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2b680 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
2b690 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
2b6a0 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
2b6b0 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
2b6c0 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
2b6d0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2b6e0 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
2b6f0 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
2b700 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
2b710 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
2b720 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
2b730 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
2b740 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
2b750 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
2b760 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
2b770 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
2b780 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
2b790 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
2b7a0 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
2b7b0 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
2b7c0 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
2b7d0 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
2b7e0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
2b7f0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2b800 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
2b810 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2b820 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
2b830 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
2b840 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20  r table row, in 
2b850 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a  bytes.<dd>)^.**.
2b860 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2b870 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e  T_SQL_LENGTH]] ^
2b880 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2b890 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
2b8a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2b8b0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
2b8c0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
2b8d0 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
2b8e0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2b8f0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20  _LIMIT_COLUMN]] 
2b900 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2b910 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
2b920 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2b930 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
2b940 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
2b950 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
2b960 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
2b970 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
2b980 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
2b990 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2b9a0 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
2b9b0 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
2b9c0 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
2b9d0 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
2b9e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2b9f0 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e  T_EXPR_DEPTH]] ^
2ba00 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2ba10 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
2ba20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2ba30 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
2ba40 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
2ba50 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
2ba60 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2ba70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
2ba80 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28  OUND_SELECT]] ^(
2ba90 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
2baa0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
2bab0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2bac0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2bad0 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
2bae0 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
2baf0 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
2bb00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
2bb10 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e  IMIT_VDBE_OP]] ^
2bb20 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2bb30 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
2bb40 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2bb50 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
2bb60 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
2bb70 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
2bb80 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
2bb90 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
2bba0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  L statement.  Th
2bbb0 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  is limit is not 
2bbc0 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66  currently.** enf
2bbd0 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68  orced, though th
2bbe0 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65  at might be adde
2bbf0 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  d in some future
2bc00 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
2bc10 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  QLite.</dd>)^.**
2bc20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2bc30 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
2bc40 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2bc50 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2bc60 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
2bc70 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2bc80 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
2bc90 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
2bca0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2bcb0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
2bcc0 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  D]] ^(<dt>SQLITE
2bcd0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
2bce0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
2bcf0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
2bd00 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
2bd10 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
2bd20 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
2bd30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
2bd40 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
2bd50 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
2bd60 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
2bd70 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
2bd80 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
2bd90 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
2bda0 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
2bdb0 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
2bdc0 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
2bdd0 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
2bde0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
2bdf0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
2be00 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  UMBER]].** ^(<dt
2be10 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
2be20 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
2be30 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2be40 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
2be50 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
2be60 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
2be70 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
2be80 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
2be90 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d  T_TRIGGER_DEPTH]
2bea0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2beb0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
2bec0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2bed0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
2bee0 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
2bef0 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
2bf00 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2bf10 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
2bf20 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53  HREADS]] ^(<dt>S
2bf30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
2bf40 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a  ER_THREADS</dt>.
2bf50 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
2bf60 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78  um number of aux
2bf70 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68  iliary worker th
2bf80 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e  reads that a sin
2bf90 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  gle.** [prepared
2bfa0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20   statement] may 
2bfb0 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  start.</dd>)^.**
2bfc0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
2bfd0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
2bfe0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
2bff0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
2c000 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2c010 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
2c020 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
2c030 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2c040 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
2c050 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
2c060 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
2c070 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
2c080 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
2c090 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
2c0a0 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
2c0b0 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
2c0c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
2c0d0 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
2c0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
2c0f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2c100 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
2c110 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
2c120 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c130 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
2c140 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c150 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
2c160 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
2c170 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
2c180 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
2c190 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2c1a0 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
2c1b0 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
2c1c0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
2c1d0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
2c1e0 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
2c1f0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
2c200 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20  _THREADS        
2c210 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     11../*.** CAP
2c220 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
2c230 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2c240 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
2c250 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
2c260 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  mpiler}.** METHO
2c270 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f  D: sqlite3.** CO
2c280 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
2c290 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f  e3_stmt.**.** To
2c2a0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
2c2b0 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
2c2c0 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
2c2d0 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
2c2e0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
2c2f0 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
2c300 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
2c310 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2c320 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
2c330 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2c340 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
2c350 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
2c360 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
2c370 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2c380 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2c390 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
2c3a0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
2c3b0 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
2c3c0 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
2c3d0 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
2c3e0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
2c3f0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
2c400 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
2c410 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
2c420 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
2c430 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
2c440 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
2c450 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
2c460 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
2c470 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
2c480 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
2c490 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
2c4a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
2c4b0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
2c4c0 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
2c4d0 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
2c4e0 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
2c4f0 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69  gument is negati
2c500 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ve, then zSql is
2c510 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
2c520 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
2c530 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
2c540 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c  yte is positive,
2c550 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a   then it is the.
2c560 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
2c570 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
2c580 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73  l.  ^If nByte is
2c590 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70   zero, then no p
2c5a0 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
2c5b0 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65  ment is generate
2c5c0 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
2c5d0 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74  ler knows that t
2c5e0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
2c5f0 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
2c600 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  ated, then.** th
2c610 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70  ere is a small p
2c620 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
2c630 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20  tage to passing 
2c640 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
2c650 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68  er that.** is th
2c660 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2c670 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
2c680 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
2c690 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
2c6a0 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  l-terminator..**
2c6b0 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
2c6c0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
2c6d0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
2c6e0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
2c6f0 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
2c700 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
2c710 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
2c720 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
2c730 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
2c740 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
2c750 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
2c760 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
2c770 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
2c780 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
2c790 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
2c7a0 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
2c7b0 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
2c7c0 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
2c7d0 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
2c7e0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
2c7f0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
2c800 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
2c810 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
2c820 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
2c830 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
2c840 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
2c850 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
2c860 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
2c870 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
2c880 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
2c890 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
2c8a0 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
2c8b0 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
2c8c0 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
2c8d0 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
2c8e0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
2c8f0 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
2c900 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
2c910 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
2c920 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
2c930 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
2c940 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
2c950 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
2c960 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
2c970 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
2c980 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2c990 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
2c9a0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2c9b0 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
2c9c0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
2c9d0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2c9e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2c9f0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2ca00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2ca10 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
2ca20 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
2ca30 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
2ca40 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
2ca50 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
2ca60 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
2ca70 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
2ca80 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
2ca90 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
2caa0 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
2cab0 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
2cac0 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
2cad0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2cae0 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
2caf0 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
2cb00 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
2cb10 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
2cb20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
2cb30 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
2cb40 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
2cb50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
2cb60 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
2cb70 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
2cb80 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
2cb90 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
2cba0 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
2cbb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
2cbc0 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
2cbd0 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
2cbe0 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
2cbf0 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
2cc00 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
2cc10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2cc20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2cc30 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
2cc40 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
2cc50 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
2cc60 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61   it again. As ma
2cc70 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41  ny as [SQLITE_MA
2cc80 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a  X_SCHEMA_RETRY].
2cc90 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20  ** retries will 
2cca0 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c  occur before sql
2ccb0 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65  ite3_step() give
2ccc0 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73  s up and returns
2ccd0 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f   an error..** </
2cce0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
2ccf0 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
2cd00 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
2cd10 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
2cd20 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
2cd30 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
2cd40 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
2cd50 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2cd60 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
2cd70 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
2cd80 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
2cd90 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
2cda0 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
2cdb0 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
2cdc0 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
2cdd0 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
2cde0 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
2cdf0 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
2ce00 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
2ce10 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
2ce20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
2ce30 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
2ce40 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
2ce50 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
2ce60 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
2ce70 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
2ce80 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
2ce90 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
2cea0 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
2ceb0 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
2cec0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2ced0 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
2cee0 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
2cef0 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
2cf00 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2cf10 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
2cf20 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
2cf30 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
2cf40 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
2cf50 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
2cf60 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
2cf70 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
2cf80 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
2cf90 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
2cfa0 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
2cfb0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
2cfc0 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
2cfd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
2cfe0 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
2cff0 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
2d000 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2d010 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
2d020 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
2d030 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
2d040 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
2d050 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
2d060 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
2d070 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
2d080 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
2d090 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
2d0a0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2d0b0 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
2d0c0 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
2d0d0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
2d0e0 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
2d0f0 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
2d100 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
2d110 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
2d120 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2d130 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT3] compile-t
2d140 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
2d150 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  abled..** </li>.
2d160 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ol>.*/.SQLI
2d170 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2d180 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71  e3_prepare(.  sq
2d190 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2d1a0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2d1b0 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2d1c0 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
2d1d0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2d1e0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
2d1f0 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
2d200 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
2d210 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
2d220 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
2d230 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
2d240 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
2d250 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
2d260 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
2d270 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
2d280 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
2d290 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
2d2a0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
2d2b0 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
2d2c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2d2d0 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73  _prepare_v2(.  s
2d2e0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2d2f0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2d300 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2d310 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
2d320 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2d330 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65  atement, UTF-8 e
2d340 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2d350 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2d360 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2d370 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2d380 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2d390 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2d3a0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2d3b0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2d3c0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a  .  const char **
2d3d0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2d3e0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2d3f0 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2d400 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
2d410 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2d420 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73  3_prepare16(.  s
2d430 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2d440 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2d450 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2d460 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2d470 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2d480 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2d490 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2d4a0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2d4b0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2d4c0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2d4d0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2d4e0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2d4f0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2d500 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2d510 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2d520 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2d530 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2d540 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2d550 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
2d560 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2d570 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2d580 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2d590 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2d5a0 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2d5b0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2d5c0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2d5d0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2d5e0 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  -16 encoded */. 
2d5f0 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
2d600 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
2d610 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
2d620 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
2d630 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
2d640 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
2d650 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
2d660 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f  le */.  const vo
2d670 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  id **pzTail     
2d680 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
2d690 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
2d6a0 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
2d6b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d6c0 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74   Retrieving Stat
2d6d0 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 20 4d 45 54  ement SQL.** MET
2d6e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
2d6f0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
2d700 69 74 65 33 5f 73 71 6c 28 50 29 20 69 6e 74 65  ite3_sql(P) inte
2d710 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2d720 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 70  pointer to a cop
2d730 79 20 6f 66 20 74 68 65 20 55 54 46 2d 38 0a 2a  y of the UTF-8.*
2d740 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
2d750 74 6f 20 63 72 65 61 74 65 20 5b 70 72 65 70 61  to create [prepa
2d760 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2d770 20 69 66 20 50 20 77 61 73 0a 2a 2a 20 63 72 65   if P was.** cre
2d780 61 74 65 64 20 62 79 20 65 69 74 68 65 72 20 5b  ated by either [
2d790 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2d7a0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
2d7b0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2d7c0 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  ]..** ^The sqlit
2d7d0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2d7e0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2d7f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2d800 6f 20 61 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  o a UTF-8.** str
2d810 69 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ing containing t
2d820 68 65 20 53 51 4c 20 74 65 78 74 20 6f 66 20 70  he SQL text of p
2d830 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d840 74 20 50 20 77 69 74 68 0a 2a 2a 20 5b 62 6f 75  t P with.** [bou
2d850 6e 64 20 70 61 72 61 6d 65 74 65 72 73 5d 20 65  nd parameters] e
2d860 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  xpanded..**.** ^
2d870 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
2d880 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2d890 65 6d 65 6e 74 20 69 73 20 63 72 65 61 74 65 64  ement is created
2d8a0 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 0a 2a   using the SQL.*
2d8b0 2a 20 74 65 78 74 20 22 53 45 4c 45 43 54 20 24  * text "SELECT $
2d8c0 61 62 63 2c 3a 78 79 7a 22 20 61 6e 64 20 69 66  abc,:xyz" and if
2d8d0 20 70 61 72 61 6d 65 74 65 72 20 24 61 62 63 20   parameter $abc 
2d8e0 69 73 20 62 6f 75 6e 64 20 74 6f 20 69 6e 74 65  is bound to inte
2d8f0 67 65 72 20 32 33 34 35 0a 2a 2a 20 61 6e 64 20  ger 2345.** and 
2d900 70 61 72 61 6d 65 74 65 72 20 3a 78 79 7a 20 69  parameter :xyz i
2d910 73 20 75 6e 62 6f 75 6e 64 2c 20 74 68 65 6e 20  s unbound, then 
2d920 73 71 6c 69 74 65 33 5f 73 71 6c 28 29 20 77 69  sqlite3_sql() wi
2d930 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  ll return.** the
2d940 20 6f 72 69 67 69 6e 61 6c 20 73 74 72 69 6e 67   original string
2d950 2c 20 22 53 45 4c 45 43 54 20 24 61 62 63 2c 3a  , "SELECT $abc,:
2d960 78 79 7a 22 20 62 75 74 20 73 71 6c 69 74 65 33  xyz" but sqlite3
2d970 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 0a  _expanded_sql().
2d980 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 22  ** will return "
2d990 53 45 4c 45 43 54 20 32 33 34 35 2c 4e 55 4c 4c  SELECT 2345,NULL
2d9a0 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ".)^.**.** ^The 
2d9b0 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2d9c0 5f 73 71 6c 28 29 20 69 6e 74 65 72 66 61 63 65  _sql() interface
2d9d0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 69 66   returns NULL if
2d9e0 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65   insufficient me
2d9f0 6d 6f 72 79 0a 2a 2a 20 69 73 20 61 76 61 69 6c  mory.** is avail
2da00 61 62 6c 65 20 74 6f 20 68 6f 6c 64 20 74 68 65  able to hold the
2da10 20 72 65 73 75 6c 74 2c 20 6f 72 20 69 66 20 74   result, or if t
2da20 68 65 20 72 65 73 75 6c 74 20 77 6f 75 6c 64 20  he result would 
2da30 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 74 68  exceed the.** th
2da40 65 20 6d 61 78 69 6d 75 6d 20 73 74 72 69 6e 67  e maximum string
2da50 20 6c 65 6e 67 74 68 20 64 65 74 65 72 6d 69 6e   length determin
2da60 65 64 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ed by the [SQLIT
2da70 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 2e  E_LIMIT_LENGTH].
2da80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
2da90 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c  ITE_TRACE_SIZE_L
2daa0 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  IMIT] compile-ti
2dab0 6d 65 20 6f 70 74 69 6f 6e 20 6c 69 6d 69 74 73  me option limits
2dac0 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
2dad0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 20  bound parameter 
2dae0 65 78 70 61 6e 73 69 6f 6e 73 2e 20 20 5e 54 68  expansions.  ^Th
2daf0 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 54  e [SQLITE_OMIT_T
2db00 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  RACE] compile-ti
2db10 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 63 61 75  me.** option cau
2db20 73 65 73 20 73 71 6c 69 74 65 33 5f 65 78 70 61  ses sqlite3_expa
2db30 6e 64 65 64 5f 73 71 6c 28 29 20 74 6f 20 61 6c  nded_sql() to al
2db40 77 61 79 73 20 72 65 74 75 72 6e 20 4e 55 4c 4c  ways return NULL
2db50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 74 72  ..**.** ^The str
2db60 69 6e 67 20 72 65 74 75 72 6e 65 64 20 62 79 20  ing returned by 
2db70 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20 69  sqlite3_sql(P) i
2db80 73 20 6d 61 6e 61 67 65 64 20 62 79 20 53 51 4c  s managed by SQL
2db90 69 74 65 20 61 6e 64 20 69 73 0a 2a 2a 20 61 75  ite and is.** au
2dba0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65  tomatically free
2dbb0 64 20 77 68 65 6e 20 74 68 65 20 70 72 65 70 61  d when the prepa
2dbc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
2dbd0 20 66 69 6e 61 6c 69 7a 65 64 2e 0a 2a 2a 20 5e   finalized..** ^
2dbe0 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2dbf0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 65  ned by sqlite3_e
2dc00 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 2c 20  xpanded_sql(P), 
2dc10 6f 6e 20 74 68 65 20 6f 74 68 65 72 20 68 61 6e  on the other han
2dc20 64 2c 0a 2a 2a 20 69 73 20 6f 62 74 61 69 6e 65  d,.** is obtaine
2dc30 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2dc40 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 6d 75  malloc()] and mu
2dc50 73 74 20 62 65 20 66 72 65 65 20 62 79 20 74 68  st be free by th
2dc60 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
2dc70 20 62 79 20 70 61 73 73 69 6e 67 20 69 74 20 74   by passing it t
2dc80 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
2dc90 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2dca0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2dcb0 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
2dcc0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2dcd0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
2dce0 2a 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65  *sqlite3_expande
2dcf0 64 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  d_sql(sqlite3_st
2dd00 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2dd10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
2dd20 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
2dd30 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65   Statement Write
2dd40 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a  s The Database.*
2dd50 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2dd60 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
2dd70 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
2dd80 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72  eadonly(X) inter
2dd90 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2dda0 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a  e (non-zero) if.
2ddb0 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  ** and only if t
2ddc0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ddd0 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20  tement] X makes 
2dde0 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65  no direct change
2ddf0 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  s to.** the cont
2de00 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
2de10 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  ase file..**.** 
2de20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69  Note that [appli
2de30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2de40 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
2de50 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
2de60 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67  les] might chang
2de70 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  e the database i
2de80 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73  ndirectly as a s
2de90 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a  ide effect.  .**
2dea0 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2deb0 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
2dec0 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63  n defines a func
2ded0 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68  tion "eval()" th
2dee0 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71  at .** calls [sq
2def0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74  lite3_exec()], t
2df00 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  hen the followin
2df10 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  g SQL statement 
2df20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20  would.** change 
2df30 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2df40 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65  e through side-e
2df50 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ffects:.**.** <b
2df60 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
2df70 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61  **    SELECT eva
2df80 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  l('DELETE FROM t
2df90 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20  1') FROM t2;.** 
2dfa0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
2dfb0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65  te>.**.** But be
2dfc0 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43  cause the [SELEC
2dfd0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  T] statement doe
2dfe0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
2dff0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
2e000 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69  * directly, sqli
2e010 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2e020 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20  y() would still 
2e030 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a  return true.)^.*
2e040 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f  *.** ^Transactio
2e050 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d  n control statem
2e060 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45  ents such as [BE
2e070 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20  GIN], [COMMIT], 
2e080 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b  [ROLLBACK],.** [
2e090 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20  SAVEPOINT], and 
2e0a0 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20  [RELEASE] cause 
2e0b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2e0c0 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
2e0d0 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65  n true,.** since
2e0e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   the statements 
2e0f0 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f  themselves do no
2e100 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66  t actually modif
2e110 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62  y the database b
2e120 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65  ut.** rather the
2e130 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69  y control the ti
2e140 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68  ming of when oth
2e150 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f  er statements mo
2e160 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74  dify the .** dat
2e170 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54  abase.  ^The [AT
2e180 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43  TACH] and [DETAC
2e190 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c  H] statements al
2e1a0 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69  so cause.** sqli
2e1b0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
2e1c0 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
2e1d0 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20  ue since, while 
2e1e0 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73  those statements
2e1f0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63  .** change the c
2e200 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20  onfiguration of 
2e210 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
2e220 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e  ction, they do n
2e230 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e  ot make .** chan
2e240 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65  ges to the conte
2e250 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
2e260 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b  se files on disk
2e270 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2e280 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2e290 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2e2a0 72 6e 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45  rns true for [BE
2e2b0 47 49 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42  GIN] since.** [B
2e2c0 45 47 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74  EGIN] merely set
2e2d0 73 20 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73  s internal flags
2e2e0 2c 20 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e  , but the [BEGIN
2e2f0 7c 42 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45  |BEGIN IMMEDIATE
2e300 5d 20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c  ] and.** [BEGIN|
2e310 42 45 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d  BEGIN EXCLUSIVE]
2e320 20 63 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75   commands do tou
2e330 63 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ch the database 
2e340 61 6e 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65  and so.** sqlite
2e350 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2e360 29 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  ) returns false 
2e370 66 6f 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e  for those comman
2e380 64 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ds..*/.SQLITE_AP
2e390 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
2e3a0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69  mt_readonly(sqli
2e3b0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2e3c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e3d0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
2e3e0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2e3f0 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65  ment Has Been Re
2e400 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
2e410 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2e420 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
2e430 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65  tmt_busy(S) inte
2e440 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
2e450 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
2e460 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2e470 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68  d statement] S h
2e480 61 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20  as been stepped 
2e490 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73  at least once us
2e4a0 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ing .** [sqlite3
2e4b0 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61  _step(S)] but ha
2e4c0 73 20 6e 65 69 74 68 65 72 20 72 75 6e 20 74 6f  s neither run to
2e4d0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28 72 65 74   completion (ret
2e4e0 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2e4f0 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b 73 71 6c  _DONE] from [sql
2e500 69 74 65 33 5f 73 74 65 70 28 53 29 5d 29 20 6e  ite3_step(S)]) n
2e510 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74  or.** been reset
2e520 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2e530 72 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65  reset(S)].  ^The
2e540 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2e550 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61  sy(S).** interfa
2e560 63 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  ce returns false
2e570 20 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20   if S is a NULL 
2e580 70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69  pointer.  If S i
2e590 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c  s not a .** NULL
2e5a0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20   pointer and is 
2e5b0 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  not a pointer to
2e5c0 20 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72   a valid [prepar
2e5d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2e5e0 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68   object, then th
2e5f0 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2e600 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
2e610 61 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65  ably undesirable
2e620 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
2e630 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2e640 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f  ed in combinatio
2e650 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  n [sqlite3_next_
2e660 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f  stmt()].** to lo
2e670 63 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65  cate all prepare
2e680 64 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73  d statements ass
2e690 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64  ociated with a d
2e6a0 61 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e  atabase .** conn
2e6b0 65 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20  ection that are 
2e6c0 69 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67  in need of being
2e6d0 20 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61   reset.  This ca
2e6e0 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f  n be used,.** fo
2e6f0 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69  r example, in di
2e700 61 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65  agnostic routine
2e710 73 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20  s to search for 
2e720 70 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61  prepared .** sta
2e730 74 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65  tements that are
2e740 20 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73   holding a trans
2e750 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a  action open..*/.
2e760 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2e770 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
2e780 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2e790 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e7a0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
2e7b0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
2e7c0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
2e7d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e7e0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
2e7f0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e800 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
2e810 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
2e820 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
2e830 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
2e840 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
2e850 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
2e860 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
2e870 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
2e880 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
2e890 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
2e8a0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
2e8b0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
2e8c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2e8d0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
2e8e0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
2e8f0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
2e900 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
2e910 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
2e920 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e930 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
2e940 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
2e950 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
2e960 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
2e970 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
2e980 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2e990 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
2e9a0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
2e9b0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
2e9c0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
2e9d0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
2e9e0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
2e9f0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
2ea00 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
2ea10 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
2ea20 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
2ea30 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
2ea40 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
2ea50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2ea60 76 61 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  value.  The.** [
2ea70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75  sqlite3_value_du
2ea80 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63  p()] interface c
2ea90 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f  an be used to co
2eaa0 6e 73 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a  nstruct a new .*
2eab0 2a 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  * protected sqli
2eac0 74 65 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61  te3_value from a
2ead0 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
2eae0 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a  lite3_value..**.
2eaf0 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70 72  ** The terms "pr
2eb00 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e  otected" and "un
2eb10 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65 72  protected" refer
2eb20 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e   to whether or n
2eb30 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73  ot.** a mutex is
2eb40 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72   held.  An inter
2eb50 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c  nal mutex is hel
2eb60 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65  d for a protecte
2eb70 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2eb80 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f  ue object but no
2eb90 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
2eba0 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2ebb0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2ebc0 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53  ue object.  If S
2ebd0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
2ebe0 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74  d to be single-t
2ebf0 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68  hreaded.** (with
2ec00 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
2ec10 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20  AFE=0] and with 
2ec20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73  [sqlite3_threads
2ec30 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67  afe()] returning
2ec40 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c   0).** or if SQL
2ec50 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e  ite is run in on
2ec60 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74  e of reduced mut
2ec70 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51  ex modes .** [SQ
2ec80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
2ec90 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51  LETHREAD] or [SQ
2eca0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2ecb0 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e  ITHREAD].** then
2ecc0 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73   there is no dis
2ecd0 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2ece0 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2ecf0 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2ed00 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2ed10 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e  cts and they can
2ed20 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63 68   be used interch
2ed30 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76  angeably.  Howev
2ed40 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d  er,.** for maxim
2ed50 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c  um code portabil
2ed60 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  ity it is recomm
2ed70 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
2ed80 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c  cations.** still
2ed90 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
2eda0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
2edb0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
2edc0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
2edd0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2ede0 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73   even when not s
2edf0 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65 64  trictly required
2ee00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2ee10 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2ee20 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73 73  ts that are pass
2ee30 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72 73  ed as parameters
2ee40 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70   into the.** imp
2ee50 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
2ee60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2ee70 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2ee80 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65 64  s] are protected
2ee90 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2eea0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72  3_value object r
2eeb0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2eec0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2eed0 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74  lue()] is unprot
2eee0 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74  ected..** Unprot
2eef0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2ef00 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20  lue objects may 
2ef10 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
2ef20 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  h.** [sqlite3_re
2ef30 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e  sult_value()] an
2ef40 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2ef50 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65  value()]..** The
2ef60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2ef70 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76  blob | sqlite3_v
2ef80 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d  alue_type()] fam
2ef90 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ily of.** interf
2efa0 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72 6f  aces require pro
2efb0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2efc0 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f  alue objects..*/
2efd0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2efe0 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  Mem sqlite3_valu
2eff0 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  e;../*.** CAPI3R
2f000 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  EF: SQL Function
2f010 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a   Context Object.
2f020 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78  **.** The contex
2f030 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51  t in which an SQ
2f040 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75  L function execu
2f050 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e  tes is stored in
2f060 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   an.** sqlite3_c
2f070 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20  ontext object.  
2f080 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ^A pointer to an
2f090 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2f0a0 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c   object.** is al
2f0b0 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61 6d  ways first param
2f0c0 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61  eter to [applica
2f0d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2f0e0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2f0f0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  The application-
2f100 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2f110 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2f120 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68  ion will pass th
2f130 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68  is.** pointer th
2f140 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73  rough into calls
2f150 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2f160 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  ult_int | sqlite
2f170 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20  3_result()],.** 
2f180 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61  [sqlite3_aggrega
2f190 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b  te_context()], [
2f1a0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
2f1b0 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  a()],.** [sqlite
2f1c0 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2f1d0 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  dle()], [sqlite3
2f1e0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c  _get_auxdata()],
2f1f0 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69  .** and/or [sqli
2f200 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
2f210 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
2f220 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f  truct sqlite3_co
2f230 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f  ntext sqlite3_co
2f240 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ntext;../*.** CA
2f250 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20  PI3REF: Binding 
2f260 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72  Values To Prepar
2f270 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed Statements.**
2f280 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74   KEYWORDS: {host
2f290 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73   parameter} {hos
2f2a0 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68  t parameters} {h
2f2b0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
2f2c0 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  me}.** KEYWORDS:
2f2d0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d   {SQL parameter}
2f2e0 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   {SQL parameters
2f2f0 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  } {parameter bin
2f300 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ding}.** METHOD:
2f310 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2f320 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
2f330 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
2f340 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
2f350 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2f360 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
2f370 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
2f380 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
2f390 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
2f3a0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
2f3b0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
2f3c0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
2f3d0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
2f3e0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
2f3f0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
2f400 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
2f410 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
2f420 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
2f430 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
2f440 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
2f450 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
2f460 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
2f470 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
2f480 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
2f490 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
2f4a0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
2f4b0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
2f4c0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
2f4d0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
2f4e0 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
2f4f0 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
2f500 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
2f510 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2f520 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
2f530 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
2f540 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2f550 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
2f560 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
2f570 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
2f580 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
2f590 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
2f5a0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
2f5b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2f5c0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
2f5d0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
2f5e0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
2f5f0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
2f600 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
2f610 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
2f620 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
2f630 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
2f640 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2f650 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
2f660 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
2f670 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
2f680 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
2f690 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
2f6a0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
2f6b0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
2f6c0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
2f6d0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
2f6e0 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
2f6f0 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
2f700 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
2f710 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
2f720 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
2f730 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2f740 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
2f750 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
2f760 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
2f770 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
2f780 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
2f790 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
2f7a0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
2f7b0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
2f7c0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
2f7d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
2f7e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2f7f0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
2f800 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
2f810 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
2f820 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
2f830 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
2f840 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
2f850 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
2f860 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
2f870 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2f880 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2f890 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2f8a0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2f8b0 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55  d_blob() is a NU
2f8c0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
2f8d0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2f8e0 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72  eter.** is ignor
2f8f0 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72  ed and the end r
2f900 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d  esult is the sam
2f910 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e  e as sqlite3_bin
2f920 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20  d_null()..**.** 
2f930 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
2f940 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
2f950 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
2f960 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
2f970 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
2f980 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
2f990 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
2f9a0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
2f9b0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2f9c0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
2f9d0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
2f9e0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2f9f0 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
2fa00 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
2fa10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2fa20 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2fa30 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2fa40 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20  _text16().** is 
2fa50 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
2fa60 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
2fa70 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
2fa80 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2fa90 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
2faa0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
2fab0 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  r..** If the fou
2fac0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2fad0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2fae0 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  ob() is negative
2faf0 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65  , then.** the be
2fb00 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2fb10 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  ned..** If a non
2fb20 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
2fb30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
2fb40 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
2fb50 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
2fb60 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2fb70 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c  _text16() or sql
2fb80 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34  ite3_bind_text64
2fb90 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20  () then.** that 
2fba0 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62  parameter must b
2fbb0 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65  e the byte offse
2fbc0 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e  t.** where the N
2fbd0 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
2fbe0 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69  uld occur assumi
2fbf0 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65  ng the string we
2fc00 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e  re NUL.** termin
2fc10 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55  ated.  If any NU
2fc20 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63  L characters occ
2fc30 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65  ur at byte offse
2fc40 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a  ts less than .**
2fc50 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
2fc60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2fc70 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  er then the resu
2fc80 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c  lting string val
2fc90 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61  ue will.** conta
2fca0 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
2fcb0 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66  .  The result of
2fcc0 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76   expressions inv
2fcd0 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a  olving strings.*
2fce0 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  * with embedded 
2fcf0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
2fd00 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  d..**.** ^The fi
2fd10 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
2fd20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72  the BLOB and str
2fd30 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65  ing binding inte
2fd40 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64  rfaces.** is a d
2fd50 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
2fd60 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
2fd70 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
2fd80 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
2fd90 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
2fda0 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
2fdb0 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
2fdc0 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
2fdd0 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
2fde0 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
2fdf0 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50   call to bind AP
2fe00 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20  I fails..** ^If 
2fe10 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2fe20 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
2fe30 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
2fe40 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
2fe50 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
2fe60 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
2fe70 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
2fe80 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
2fe90 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
2fea0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
2feb0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
2fec0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
2fed0 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
2fee0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
2fef0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
2ff00 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
2ff10 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
2ff20 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
2ff30 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
2ff40 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2ff50 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2ff60 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
2ff70 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ixth argument to
2ff80 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2ff90 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f  xt64() must be o
2ffa0 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45  ne of.** [SQLITE
2ffb0 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
2ffc0 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f  UTF16], [SQLITE_
2ffd0 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51  UTF16BE], or [SQ
2ffe0 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a  LITE_UTF16LE].**
2fff0 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20   to specify the 
30000 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20  encoding of the 
30010 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69 72  text in the thir
30020 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66  d parameter.  If
30030 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61 72  .** the sixth ar
30040 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
30050 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20  3_bind_text64() 
30060 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
30070 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c  e.** allowed val
30080 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c  ues shown above,
30090 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74 20   or if the text 
300a0 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
300b0 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68  erent.** from th
300c0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
300d0 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78 74  fied by the sixt
300e0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  h parameter, the
300f0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  n the behavior.*
30100 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  * is undefined..
30110 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30120 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
30130 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
30140 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
30150 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
30160 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
30170 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
30180 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
30190 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
301a0 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
301b0 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
301c0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
301d0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
301e0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
301f0 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
30200 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
30210 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
30220 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
30230 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
30240 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
30250 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
30260 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
30270 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
30280 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
30290 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
302a0 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
302b0 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
302c0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
302d0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
302e0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
302f0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
30300 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
30310 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
30320 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
30330 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
30340 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
30350 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
30360 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
30370 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
30380 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
30390 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
303a0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
303b0 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
303c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
303d0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
303e0 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
303f0 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
30400 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30410 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
30420 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
30430 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
30440 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
30450 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
30460 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
30470 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
30480 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
30490 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
304a0 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
304b0 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
304c0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
304d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
304e0 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
304f0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
30500 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
30510 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
30520 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
30530 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
30540 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49  * ^[SQLITE_TOOBI
30550 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  G] might be retu
30560 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a 65  rned if the size
30570 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20   of a string or 
30580 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20  BLOB.** exceeds 
30590 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62  limits imposed b
305a0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
305b0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
305c0 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b  LENGTH]) or.** [
305d0 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54  SQLITE_MAX_LENGT
305e0 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  H]..** ^[SQLITE_
305f0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
30600 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
30610 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
30620 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
30630 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
30640 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
30650 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
30660 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
30670 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30680 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
30690 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
306a0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
306b0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
306c0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
306d0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
306e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
306f0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
30700 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
30710 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
30720 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
30730 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
30740 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
30750 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  nd_blob64(sqlite
30760 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
30770 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74  nst void*, sqlit
30780 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
30790 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
307a0 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
307b0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
307c0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
307d0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
307e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c  tmt*, int, doubl
307f0 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  e);.SQLITE_API i
30800 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
30810 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
30820 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51  *, int, int);.SQ
30830 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
30840 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28  ite3_bind_int64(
30850 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30860 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  nt, sqlite3_int6
30870 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  4);.SQLITE_API i
30880 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
30890 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
308a0 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  t*, int);.SQLITE
308b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
308c0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
308d0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f 6e  e3_stmt*,int,con
308e0 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f 69  st char*,int,voi
308f0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
30900 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
30910 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
30920 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
30930 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
30940 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
30950 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
30960 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
30970 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69 74  ind_text64(sqlit
30980 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
30990 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
309a0 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
309b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
309c0 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
309d0 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63 68  d*), unsigned ch
309e0 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53 51  ar encoding);.SQ
309f0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
30a00 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
30a10 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30a20 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65  nt, const sqlite
30a30 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
30a40 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
30a50 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
30a60 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30a70 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 53 51 4c 49  nt, int n);.SQLI
30a80 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
30a90 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
30aa0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
30ab0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 75  , int, sqlite3_u
30ac0 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int64);../*.** C
30ad0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
30ae0 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72  Of SQL Parameter
30af0 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
30b00 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
30b10 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
30b20 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
30b30 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
30b40 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
30b50 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
30b60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
30b70 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
30b80 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
30b90 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
30ba0 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
30bb0 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
30bc0 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
30bd0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
30be0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
30bf0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
30c00 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
30c10 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
30c20 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
30c30 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
30c40 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
30c50 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
30c60 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
30c70 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
30c80 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
30c90 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
30ca0 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
30cb0 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
30cc0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
30cd0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
30ce0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
30cf0 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
30d00 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
30d10 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
30d20 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
30d30 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
30d40 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
30d50 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
30d60 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
30d70 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30d80 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
30d90 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
30da0 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
30db0 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
30dc0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
30dd0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
30de0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
30df0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30e00 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
30e10 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20 4d  t Parameter.** M
30e20 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
30e30 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
30e40 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30e50 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20  meter_name(P,N) 
30e60 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
30e70 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
30e80 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70   the N-th [SQL p
30e90 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
30ea0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
30eb0 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51  ment] P..** ^(SQ
30ec0 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20  L parameters of 
30ed0 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20  the form "?NNN" 
30ee0 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
30ef0 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
30f00 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68 69   have a name whi
30f10 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e 67  ch is the string
30f20 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
30f30 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
30f40 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63 74  $AAA".** respect
30f50 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68  ively..** In oth
30f60 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69 6e  er words, the in
30f70 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24 22  itial ":" or "$"
30f80 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a   or "@" or "?".*
30f90 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61 73  * is included as
30fa0 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61 6d   part of the nam
30fb0 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74  e.)^.** ^Paramet
30fc0 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
30fd0 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66 6f  "?" without a fo
30fe0 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72 20  llowing integer 
30ff0 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20  have no name.** 
31000 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65 64  and are referred
31010 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73 73   to as "nameless
31020 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20  " or "anonymous 
31030 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a  parameters"..**.
31040 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68 6f  ** ^The first ho
31050 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61 73  st parameter has
31060 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c 20   an index of 1, 
31070 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  not 0..**.** ^If
31080 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73 20   the value N is 
31090 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72 20  out of range or 
310a0 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72 61  if the N-th para
310b0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65  meter is.** name
310c0 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20  less, then NULL 
310d0 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e 54  is returned.  ^T
310e0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
310f0 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20  ng is.** always 
31100 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  in UTF-8 encodin
31110 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e 61  g even if the na
31120 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77 61  med parameter wa
31130 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20  s.** originally 
31140 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54 46  specified as UTF
31150 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  -16 in [sqlite3_
31160 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72 0a  prepare16()] or.
31170 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
31180 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
31190 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
311a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
311b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
311c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
311d0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
311e0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
311f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
31200 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
31210 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
31220 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
31230 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
31240 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
31250 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
31260 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
31270 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
31280 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
31290 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
312a0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
312b0 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
312c0 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
312d0 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
312e0 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
312f0 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
31300 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
31310 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
31320 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
31330 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
31340 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
31350 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
31360 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
31370 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
31380 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
31390 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
313a0 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
313b0 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
313c0 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
313d0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
313e0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
313f0 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
31400 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
31410 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
31420 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
31430 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
31440 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
31450 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
31460 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
31470 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
31480 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
31490 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
314a0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
314b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
314c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
314d0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
314e0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
314f0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
31500 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
31510 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
31520 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
31530 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
31540 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
31550 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
31560 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
31570 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
31580 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
31590 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
315a0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
315b0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
315c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
315d0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
315e0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
315f0 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
31600 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
31610 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
31620 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65 61  int sqlite3_clea
31630 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74  r_bindings(sqlit
31640 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
31650 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
31660 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e  er Of Columns In
31670 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
31680 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
31690 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  _stmt.**.** ^Ret
316a0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
316b0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
316c0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
316d0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
316e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
316f0 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
31700 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
31710 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
31720 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
31730 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
31740 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
31750 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
31760 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
31770 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
31780 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49  count()].*/.SQLI
31790 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
317a0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
317b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
317c0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
317d0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
317e0 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
317f0 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  Set.** METHOD: s
31800 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
31810 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
31820 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
31830 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
31840 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
31850 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
31860 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
31870 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
31880 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
31890 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
318a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
318b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
318c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
318d0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
318e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
318f0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
31900 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
31910 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
31920 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
31930 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
31940 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
31950 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
31960 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
31970 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
31980 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
31990 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
319a0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
319b0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
319c0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
319d0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
319e0 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
319f0 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
31a00 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
31a10 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
31a20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31a30 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
31a40 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
31a50 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
31a60 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
31a70 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
31a80 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
31a90 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
31aa0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
31ab0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
31ac0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
31ad0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
31ae0 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
31af0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
31b00 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
31b10 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
31b20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
31b30 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
31b40 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
31b50 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
31b60 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
31b70 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
31b80 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
31b90 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
31ba0 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
31bb0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
31bc0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
31bd0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
31be0 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
31bf0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
31c00 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
31c10 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
31c20 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
31c30 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
31c40 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
31c50 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
31c60 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
31c70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
31c80 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
31c90 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
31ca0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
31cb0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
31cc0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
31cd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
31ce0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
31cf0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69  column_name(sqli
31d00 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
31d10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
31d20 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
31d30 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
31d40 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31d50 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt N);../*.** CA
31d60 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20 4f  PI3REF: Source O
31d70 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65 72  f Data In A Quer
31d80 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
31d90 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
31da0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
31db0 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
31dc0 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
31dd0 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
31de0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
31df0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
31e00 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
31e10 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
31e20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
31e30 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
31e40 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
31e50 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
31e60 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
31e70 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
31e80 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
31e90 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
31ea0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
31eb0 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
31ec0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
31ed0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
31ee0 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
31ef0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
31f00 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
31f10 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
31f20 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
31f30 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
31f40 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
31f50 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
31f60 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
31f70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31f80 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
31f90 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
31fa0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
31fb0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
31fc0 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
31fd0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
31fe0 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
31ff0 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
32000 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
32010 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
32020 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
32030 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
32040 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
32050 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
32060 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
32070 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
32080 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
32090 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
320a0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
320b0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
320c0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
320d0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
320e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
320f0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
32100 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
32110 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
32120 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
32130 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
32140 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
32150 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
32160 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
32170 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
32180 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
32190 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
321a0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
321b0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
321c0 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
321d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
321e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
321f0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
32200 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
32210 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
32220 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
32230 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
32240 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
32250 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
32260 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
32270 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
32280 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
32290 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
322a0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
322b0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
322c0 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
322d0 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
322e0 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
322f0 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
32300 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
32310 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
32320 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
32330 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
32340 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
32350 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
32360 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
32370 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
32380 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
32390 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
323a0 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
323b0 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
323c0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
323d0 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
323e0 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
323f0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
32400 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
32410 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
32420 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
32430 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
32440 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
32450 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
32460 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
32470 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
32480 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
32490 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
324a0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
324b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
324c0 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
324d0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
324e0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
324f0 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
32500 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
32510 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
32520 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
32530 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
32540 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
32550 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
32560 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
32570 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
32580 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
32590 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
325a0 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
325b0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
325c0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
325d0 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ined..*/.SQLITE_
325e0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
325f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
32600 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
32610 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
32620 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
32630 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
32640 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
32650 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
32660 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
32670 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
32680 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
32690 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
326a0 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
326b0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
326c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
326d0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
326e0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
326f0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
32700 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
32710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
32720 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
32730 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
32740 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
32750 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
32760 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
32770 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32780 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
32790 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
327a0 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
327b0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54  ry Result.** MET
327c0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
327d0 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  t.**.** ^(The fi
327e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
327f0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
32800 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74  tement]..** If t
32810 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73  his statement is
32820 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
32830 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74  ement and the Nt
32840 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a  h column of the.
32850 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75  ** returned resu
32860 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b  lt set of that [
32870 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62  SELECT] is a tab
32880 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61  le column (not a
32890 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
328a0 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65  or subquery) the
328b0 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  n the declared t
328c0 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ype of the table
328d0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65  .** column is re
328e0 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74  turned.)^  ^If t
328f0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
32900 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
32910 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  is an.** express
32920 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c  ion or subquery,
32930 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69   then a NULL poi
32940 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
32950 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
32960 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77  ed string is alw
32970 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ays UTF-8 encode
32980 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65  d..**.** ^(For e
32990 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68  xample, given th
329a0 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d  e database schem
329b0 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20  a:.**.** CREATE 
329c0 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49  TABLE t1(c1 VARI
329d0 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20  ANT);.**.** and 
329e0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74  the following st
329f0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
32a00 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45  mpiled:.**.** SE
32a10 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20  LECT c1 + 1, c1 
32a20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74  FROM t1;.**.** t
32a30 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c  his routine woul
32a40 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72  d return the str
32a50 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f  ing "VARIANT" fo
32a60 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73  r the second res
32a70 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69  ult.** column (i
32a80 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c  ==1), and a NULL
32a90 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
32aa0 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f   first result co
32ab0 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a  lumn (i==0).)^.*
32ac0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
32ad0 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69  s dynamic run-ti
32ae0 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20  me typing.  ^So 
32af0 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63  just because a c
32b00 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c  olumn.** is decl
32b10 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  ared to contain 
32b20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70  a particular typ
32b30 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20  e does not mean 
32b40 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61  that the.** data
32b50 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20   stored in that 
32b60 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65  column is of the
32b70 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20   declared type. 
32b80 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74   SQLite is.** st
32b90 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75  rongly typed, bu
32ba0 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20  t the typing is 
32bb0 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74  dynamic not stat
32bc0 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73  ic.  ^Type.** is
32bd0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
32be0 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75   individual valu
32bf0 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65  es, not with the
32c00 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75   containers.** u
32c10 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73  sed to hold thos
32c20 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c  e values..*/.SQL
32c30 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
32c40 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
32c50 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69  mn_decltype(sqli
32c60 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
32c70 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
32c80 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
32c90 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
32ca0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32cb0 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
32cc0 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
32cd0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
32ce0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
32cf0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66  e3_stmt.**.** Af
32d00 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
32d10 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
32d20 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
32d30 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
32d40 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
32d50 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
32d60 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
32d70 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
32d80 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
32d90 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
32da0 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
32db0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
32dc0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
32dd0 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
32de0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
32df0 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
32e00 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
32e10 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
32e20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
32e30 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
32e40 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
32e50 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
32e60 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
32e70 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
32e80 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
32e90 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
32ea0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
32eb0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
32ec0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
32ed0 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
32ee0 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
32ef0 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
32f00 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
32f10 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
32f20 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
32f30 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
32f40 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
32f50 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
32f60 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
32f70 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
32f80 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
32f90 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
32fa0 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
32fb0 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
32fc0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
32fd0 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
32fe0 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
32ff0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
33000 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
33010 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
33020 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
33030 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
33040 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
33050 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
33060 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
33070 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
33080 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
33090 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
330a0 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
330b0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
330c0 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
330d0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
330e0 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
330f0 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
33100 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
33110 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
33120 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
33130 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
33140 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
33150 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
33160 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
33170 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
33180 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
33190 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
331a0 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
331b0 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
331c0 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
331d0 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
331e0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
331f0 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
33200 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
33210 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
33220 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
33230 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
33240 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
33250 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
33260 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
33270 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
33280 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
33290 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
332a0 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
332b0 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
332c0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
332d0 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
332e0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
332f0 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
33300 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
33310 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
33320 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
33330 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
33340 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
33350 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
33360 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
33370 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
33380 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
33390 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
333a0 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
333b0 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
333c0 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
333d0 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
333e0 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
333f0 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
33400 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
33410 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
33420 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
33430 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
33440 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
33450 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
33460 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
33470 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
33480 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
33490 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
334a0 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
334b0 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
334c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
334d0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
334e0 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
334f0 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
33500 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
33510 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
33520 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
33530 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
33540 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
33550 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
33560 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
33570 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
33580 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
33590 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
335a0 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
335b0 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
335c0 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
335d0 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
335e0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
335f0 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
33600 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33610 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
33620 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
33630 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
33640 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
33650 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
33660 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
33670 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
33680 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
33690 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
336a0 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
336b0 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
336c0 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
336d0 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
336e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
336f0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
33700 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
33710 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
33720 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
33730 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
33740 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
33750 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
33760 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
33770 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
33780 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
33790 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
337a0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
337b0 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
337c0 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
337d0 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
337e0 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
337f0 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
33800 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
33810 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
33820 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
33830 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
33840 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
33850 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
33860 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
33870 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
33880 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
33890 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
338a0 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
338b0 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
338c0 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
338d0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
338e0 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
338f0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
33900 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
33910 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
33920 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
33930 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
33940 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
33950 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
33960 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
33970 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33   [version 3.6.23
33980 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36  .1] ([dateof:3.6
33990 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74  .23.1],.** sqlit
339a0 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
339b0 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
339c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
339d0 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
339e0 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
339f0 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
33a00 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
33a10 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
33a20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
33a30 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
33a40 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
33a50 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
33a60 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
33a70 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
33a80 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
33a90 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
33aa0 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
33ab0 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
33ac0 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
33ad0 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
33ae0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
33af0 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
33b00 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
33b10 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
33b20 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
33b30 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
33b40 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
33b50 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
33b60 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
33b70 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
33b80 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
33b90 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
33ba0 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
33bb0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
33bc0 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
33bd0 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
33be0 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
33bf0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
33c00 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
33c10 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
33c20 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
33c30 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
33c40 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
33c50 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
33c60 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
33c70 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
33c80 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
33c90 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
33ca0 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
33cb0 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
33cc0 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
33cd0 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
33ce0 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
33cf0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
33d00 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
33d10 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
33d20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
33d30 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
33d40 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
33d50 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
33d60 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
33d70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
33d80 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
33d90 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
33da0 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
33db0 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
33dc0 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
33dd0 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
33de0 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
33df0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
33e00 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
33e10 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
33e20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65 70  int sqlite3_step
33e30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
33e40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33e50 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  : Number of colu
33e60 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74 20  mns in a result 
33e70 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  set.** METHOD: s
33e80 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
33e90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
33ea0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74  ata_count(P) int
33eb0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
33ec0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
33ed0 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63  umns in the.** c
33ee0 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
33ef0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
33f00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
33f10 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70  ent] P..** ^If p
33f20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33f30 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  t P does not hav
33f40 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20  e results ready 
33f50 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69  to return.** (vi
33f60 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b  a calls to the [
33f70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
33f80 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt | sqlite3_col
33f90 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69  umn_*()] of.** i
33fa0 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20  nterfaces) then 
33fb0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
33fc0 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e  nt(P) returns 0.
33fd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33fe0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
33ff0 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75  outine also retu
34000 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20  rns 0 if P is a 
34010 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
34020 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
34030 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
34040 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
34050 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
34060 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
34070 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
34080 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ned [SQLITE_DONE
34090 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
340a0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a  _data_count(P).*
340b0 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f  * will return no
340c0 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f  n-zero if previo
340d0 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  us call to [sqli
340e0 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
340f0 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
34100 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e  _ROW], except in
34110 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65   the case of the
34120 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65   [PRAGMA increme
34130 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20  ntal_vacuum].** 
34140 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20  where it always 
34150 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e  returns zero sin
34160 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20  ce each step of 
34170 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a  that multi-step.
34180 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e  ** pragma return
34190 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64  s 0 columns of d
341a0 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ata..**.** See a
341b0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
341c0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
341d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
341e0 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
341f0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
34200 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
34210 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
34220 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
34230 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
34240 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
34250 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
34260 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
34270 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
34280 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
34290 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
342a0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
342b0 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
342c0 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
342d0 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
342e0 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
342f0 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
34300 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
34310 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
34320 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
34330 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
34340 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
34350 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
34360 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
34370 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
34380 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
34390 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
343a0 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
343b0 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
343c0 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
343d0 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
343e0 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
343f0 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
34400 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
34410 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
34420 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
34430 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
34440 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
34450 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
34460 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
34470 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
34480 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
34490 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
344a0 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
344b0 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
344c0 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
344d0 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
344e0 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
344f0 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
34500 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
34510 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
34520 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
34530 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
34540 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
34550 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
34560 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
34570 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
34580 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
34590 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
345a0 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20   about a single 
345b0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75  column of the cu
345c0 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20  rrent.** result 
345d0 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
345e0 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20   ^In every case 
345f0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
34600 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
34610 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
34620 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
34630 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
34640 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
34650 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
34660 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
34670 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
34680 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
34690 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
346a0 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
346b0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
346c0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
346d0 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
346e0 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
346f0 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
34700 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66  turned. ^The lef
34710 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
34720 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
34730 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
34740 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  ** ^The number o
34750 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
34760 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64   result can be d
34770 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a  etermined using.
34780 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
34790 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a  mn_count()]..**.
347a0 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
347b0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
347c0 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
347d0 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
347e0 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
347f0 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
34800 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
34810 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
34820 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
34830 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
34840 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
34850 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
34860 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
34870 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
34880 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
34890 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
348a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
348b0 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
348c0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
348d0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
348e0 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
348f0 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
34900 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
34910 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
34920 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
34930 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
34940 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
34950 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
34960 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
34970 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
34980 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
34990 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
349a0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
349b0 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
349c0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
349d0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
349e0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
349f0 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
34a00 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
34a10 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
34a20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
34a30 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
34a40 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
34a50 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
34a60 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
34a70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34a80 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
34a90 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
34aa0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
34ab0 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
34ac0 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
34ad0 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
34ae0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
34af0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
34b00 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
34b10 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
34b20 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
34b30 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
34b40 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
34b50 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
34b60 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
34b70 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
34b80 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
34b90 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
34ba0 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
34bb0 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
34bc0 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
34bd0 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
34be0 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
34bf0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
34c00 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
34c10 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
34c20 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
34c30 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
34c40 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
34c50 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
34c60 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
34c70 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
34c80 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
34c90 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
34ca0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
34cb0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
34cc0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
34cd0 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
34ce0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
34cf0 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
34d00 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
34d10 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
34d20 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
34d30 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
34d40 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
34d50 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
34d60 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
34d70 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
34d80 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
34d90 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
34da0 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
34db0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
34dc0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
34dd0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
34de0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
34df0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
34e00 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
34e10 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
34e20 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
34e30 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
34e40 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
34e50 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
34e60 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
34e70 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
34e80 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
34e90 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
34ea0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
34eb0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
34ec0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
34ed0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
34ee0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
34ef0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
34f00 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
34f10 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
34f20 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
34f30 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
34f40 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
34f50 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
34f60 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
34f70 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
34f80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
34f90 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
34fa0 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
34fb0 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
34fc0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
34fd0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
34fe0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
34ff0 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
35000 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
35010 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
35020 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
35030 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
35040 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
35050 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
35060 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
35070 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
35080 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
35090 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
350a0 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
350b0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
350c0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
350d0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
350e0 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
350f0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
35100 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35110 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
35120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35130 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
35140 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
35150 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
35160 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
35170 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
35180 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
35190 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
351a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
351b0 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
351c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
351d0 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
351e0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
351f0 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
35200 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
35210 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
35220 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
35230 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
35240 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
35250 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
35260 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
35270 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
35280 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
35290 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
352a0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
352b0 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
352c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
352d0 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
352e0 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
352f0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
35300 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c 2f  ** <b>Warning:</
35310 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  b> ^The object r
35320 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
35330 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
35340 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
35350 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
35360 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
35370 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72 65    In a multithre
35380 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  aded environment
35390 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65 63  ,.** an unprotec
353a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
353b0 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e 6c  e object may onl
353c0 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c 79  y be used safely
353d0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
353e0 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
353f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
35400 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
35410 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
35420 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
35430 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
35440 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
35450 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
35460 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
35470 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
35480 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
35490 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
354a0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
354b0 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
354c0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
354d0 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
354e0 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
354f0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 6e  he behavior is n
35500 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a 2a  ot threadsafe..*
35510 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
35520 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63  nes attempt to c
35530 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
35540 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61   where appropria
35550 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61  te.  ^For.** exa
35560 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
35570 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
35580 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
35590 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
355a0 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
355b0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
355c0 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
355d0 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
355e0 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
355f0 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
35600 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  lly.  ^(The foll
35610 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
35620 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
35630 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
35640 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
35650 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
35660 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
35670 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
35680 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
35690 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
356a0 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
356b0 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
356c0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
356d0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
356e0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
356f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
35700 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
35710 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
35720 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
35730 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
35740 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
35750 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20  esult is a NULL 
35760 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
35770 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
35780 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
35790 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c   Result is a NUL
357a0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
357b0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
357c0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
357d0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
357e0 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
357f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
35800 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
35810 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
35820 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
35830 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
35840 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
35850 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
35860 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
35870 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
35880 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
35890 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
358a0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
358b0 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
358c0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
358d0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
358e0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
358f0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
35900 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
35910 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
35920 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42  > [CAST] to BLOB
35930 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
35940 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
35950 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
35960 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
35970 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
35980 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
35990 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
359a0 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
359b0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
359c0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
359d0 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
359e0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
359f0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
35a00 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
35a10 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  R.** <tr><td>  B
35a20 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
35a30 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  AT    <td> [CAST
35a40 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72  ] to REAL.** <tr
35a50 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
35a60 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
35a70 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
35a80 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
35a90 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
35aa0 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
35ab0 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ^.**.** Note tha
35ac0 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
35ad0 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
35ae0 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
35af0 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
35b00 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
35b10 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
35b20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35b30 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
35b40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
35b50 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
35b60 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
35b70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
35b80 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
35b90 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
35ba0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
35bb0 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
35bc0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
35bd0 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
35be0 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
35bf0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
35c00 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
35c10 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
35c20 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
35c30 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
35c40 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
35c50 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
35c60 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
35c70 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
35c80 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
35c90 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
35ca0 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
35cb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35cc0 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
35cd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35ce0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
35cf0 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
35d00 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
35d10 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
35d20 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
35d30 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
35d40 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
35d50 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
35d60 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
35d70 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
35d80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
35d90 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
35da0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
35db0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
35dc0 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
35dd0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
35de0 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
35df0 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
35e00 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
35e10 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
35e20 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
35e30 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
35e40 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
35e50 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
35e60 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
35e70 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
35e80 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
35e90 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
35ea0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
35eb0 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
35ec0 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
35ed0 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
35ee0 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
35ef0 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
35f00 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
35f10 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
35f20 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
35f30 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
35f40 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
35f50 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
35f60 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20 69   safest policy i
35f70 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
35f80 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
35f90 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
35fa0 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
35fb0 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
35fc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
35fd0 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
35fe0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35ff0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
36000 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
36010 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
36020 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
36030 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
36040 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
36050 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
36060 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
36070 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
36080 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
36090 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
360a0 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
360b0 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
360c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
360d0 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
360e0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
360f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36100 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
36110 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
36120 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
36130 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
36140 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
36150 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
36160 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
36170 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
36180 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
36190 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
361a0 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
361b0 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
361c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
361d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
361e0 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
361f0 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
36200 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
36210 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
36220 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
36230 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
36240 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
36250 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
36260 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
36270 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
36280 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
36290 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
362a0 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
362b0 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
362c0 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
362d0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
362e0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
362f0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
36300 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
36310 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
36320 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
36330 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
36340 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
36350 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
36360 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 65  atically.  Do <e
36370 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73 20  m>not</em> pass 
36380 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74  the pointers ret
36390 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
363a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
363b0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
363c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20  column_text()], 
363d0 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71  etc. into.** [sq
363e0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
363f0 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f  *.** ^(If a memo
36400 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
36410 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e  ror occurs durin
36420 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e  g the evaluation
36430 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68   of any.** of th
36440 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20  ese routines, a 
36450 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
36460 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
36470 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a  default value.**
36480 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69   is either the i
36490 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c  nteger 0, the fl
364a0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
364b0 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55  ber 0.0, or a NU
364c0 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20  LL.** pointer.  
364d0 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  Subsequent calls
364e0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72   to [sqlite3_err
364f0 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74  code()] will ret
36500 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  urn.** [SQLITE_N
36510 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49  OMEM].)^.*/.SQLI
36520 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
36530 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
36540 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  n_blob(sqlite3_s
36550 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
36560 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
36570 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36580 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
36590 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
365a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
365b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
365c0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
365d0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
365e0 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65  QLITE_API double
365f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36600 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
36610 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
36620 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
36630 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
36640 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
36650 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
36660 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
36670 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f  int64 sqlite3_co
36680 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74  lumn_int64(sqlit
36690 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
366a0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
366b0 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
366c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
366d0 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33  umn_text(sqlite3
366e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
366f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
36700 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
36710 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
36720 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36730 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
36740 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
36750 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
36760 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
36770 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
36780 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  I sqlite3_value 
36790 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
367a0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
367b0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
367c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
367d0 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
367e0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
367f0 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54  ject.** DESTRUCT
36800 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
36810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36820 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
36830 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
36840 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
36850 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36860 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
36870 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
36880 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
36890 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
368a0 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
368b0 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
368c0 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
368d0 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
368e0 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
368f0 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
36900 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
36910 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
36920 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
36930 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
36940 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
36950 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
36960 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
36970 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
36980 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
36990 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
369a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
369b0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
369c0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
369d0 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
369e0 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
369f0 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
36a00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36a10 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
36a20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
36a30 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
36a40 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
36a50 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
36a60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
36a70 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
36a80 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
36a90 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
36aa0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
36ab0 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
36ac0 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
36ad0 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
36ae0 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
36af0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
36b00 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
36b10 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
36b20 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
36b30 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
36b40 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
36b50 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
36b60 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
36b70 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
36b80 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
36b90 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
36ba0 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
36bb0 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
36bc0 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
36bd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
36be0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
36bf0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
36c00 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
36c10 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
36c20 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
36c30 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
36c40 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
36c50 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
36c60 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
36c70 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
36c80 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
36c90 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  uption..*/.SQLIT
36ca0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
36cb0 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
36cc0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
36cd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
36ce0 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
36cf0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
36d00 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ect.** METHOD: s
36d10 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
36d20 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
36d30 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
36d40 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
36d50 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
36d60 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
36d70 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
36d80 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
36d90 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
36da0 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
36db0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
36dc0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
36dd0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
36de0 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
36df0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
36e00 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
36e10 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
36e20 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
36e30 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
36e40 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
36e50 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
36e60 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
36e70 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
36e80 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
36e90 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
36ea0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36eb0 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
36ec0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
36ed0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
36ee0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
36ef0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
36f00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
36f10 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
36f20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
36f30 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
36f40 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
36f50 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
36f60 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
36f70 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
36f80 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
36f90 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
36fa0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
36fb0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
36fc0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
36fd0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
36fe0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
36ff0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
37000 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
37010 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
37020 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
37030 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
37040 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
37050 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
37060 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
37070 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
37080 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
37090 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
370a0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
370b0 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
370c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
370d0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
370e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
370f0 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
37100 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
37110 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
37120 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
37130 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
37140 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
37150 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
37160 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
37170 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
37180 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
37190 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
371a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
371b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
371c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
371d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
371e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
371f0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
37200 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  e3.**.** ^These 
37210 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65  functions (colle
37220 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73  ctively known as
37230 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74   "function creat
37240 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a  ion routines").*
37250 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64  * are used to ad
37260 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
37270 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72  or aggregates or
37280 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65   to redefine the
37290 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
372a0 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e  existing SQL fun
372b0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
372c0 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  ates.  The only 
372d0 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77  differences betw
372e0 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75  een.** these rou
372f0 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65  tines are the te
37300 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65  xt encoding expe
37310 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  cted for.** the 
37320 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
37330 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   (the name of th
37340 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67  e function being
37350 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64   created).** and
37360 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72   the presence or
37370 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65   absence of a de
37380 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63  structor callbac
37390 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70  k for.** the app
373a0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
373b0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
373c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
373d0 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61  r is the [databa
373e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
373f0 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a  o which the SQL.
37400 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ** function is t
37410 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66  o be added.  ^If
37420 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
37430 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f  uses more than o
37440 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ne database.** c
37450 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61  onnection then a
37460 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37470 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
37480 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a   must be added.*
37490 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  * to each databa
374a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65  se connection se
374b0 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
374c0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
374d0 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d  meter is the nam
374e0 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e  e of the SQL fun
374f0 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61  ction to be crea
37500 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69  ted or.** redefi
37510 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74  ned.  ^The lengt
37520 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73  h of the name is
37530 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20   limited to 255 
37540 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38  bytes in a UTF-8
37550 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69  .** representati
37560 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66  on, exclusive of
37570 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
37580 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61  ator.  ^Note tha
37590 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65  t the name.** le
375a0 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e  ngth limit is in
375b0 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f   UTF-8 bytes, no
375c0 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72  t characters nor
375d0 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20   UTF-16 bytes.  
375e0 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74  .** ^Any attempt
375f0 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e   to create a fun
37600 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e  ction with a lon
37610 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c  ger name.** will
37620 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49   result in [SQLI
37630 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67  TE_MISUSE] being
37640 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
37650 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61   ^The third para
37660 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20  meter (nArg).** 
37670 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
37680 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
37690 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
376a0 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
376b0 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73   takes. ^If this
376c0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31   parameter is -1
376d0 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66  , then the SQL f
376e0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
376f0 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65  gregate may take
37700 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61   any number of a
37710 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e  rguments between
37720 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74   0 and the limit
37730 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69  .** set by [sqli
37740 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49  te3_limit]([SQLI
37750 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
37760 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65  N_ARG]).  If the
37770 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
37780 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ter is less than
37790 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74   -1 or greater t
377a0 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65  han 127 then the
377b0 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20   behavior is.** 
377c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
377d0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
377e0 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70  ameter, eTextRep
377f0 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74  , specifies what
37800 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  .** [SQLITE_UTF8
37810 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67   | text encoding
37820 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74  ] this SQL funct
37830 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a  ion prefers for.
37840 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72  ** its parameter
37850 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  s.  The applicat
37860 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74  ion should set t
37870 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  his parameter to
37880 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
37890 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63  6LE] if the func
378a0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
378b0 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20  ion invokes .** 
378c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
378d0 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e  ext16le()] on an
378e0 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49   input, or [SQLI
378f0 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74  TE_UTF16BE] if t
37900 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
37910 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71  tion invokes [sq
37920 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37930 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16be()] on an in
37940 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  put, or.** [SQLI
37950 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71  TE_UTF16] if [sq
37960 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
37970 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f  16()] is used, o
37980 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a  r [SQLITE_UTF8].
37990 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e  ** otherwise.  ^
379a0 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  The same SQL fun
379b0 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67  ction may be reg
379c0 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65  istered multiple
379d0 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20   times using.** 
379e0 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65 72  different prefer
379f0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
37a00 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72 65  gs, with differe
37a10 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
37a20 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65  ns for.** each e
37a30 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65  ncoding..** ^Whe
37a40 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
37a50 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
37a60 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
37a70 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
37a80 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
37a90 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
37aa0 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
37ab0 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
37ac0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
37ad0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
37ae0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70  parameter may op
37af0 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64  tionally be ORed
37b00 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
37b10 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20  TERMINISTIC].** 
37b20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74  to signal that t
37b30 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  he function will
37b40 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
37b50 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67  he same result g
37b60 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  iven.** the same
37b70 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61   inputs within a
37b80 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
37b90 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c  ement.  Most SQL
37ba0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a   functions are.*
37bb0 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  * deterministic.
37bc0 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b    The built-in [
37bd0 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75  random()] SQL fu
37be0 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61  nction is an exa
37bf0 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e  mple of a.** fun
37c00 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f  ction that is no
37c10 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e  t deterministic.
37c20 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75 65    The SQLite que
37c30 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62  ry planner is ab
37c40 6c 65 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d  le to.** perform
37c50 20 61 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69   additional opti
37c60 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74  mizations on det
37c70 65 72 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74  erministic funct
37c80 69 6f 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20  ions, so use.** 
37c90 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44  of the [SQLITE_D
37ca0 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c  ETERMINISTIC] fl
37cb0 61 67 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ag is recommende
37cc0 64 20 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65  d where possible
37cd0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
37ce0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
37cf0 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
37d00 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
37d10 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
37d20 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
37d30 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
37d40 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
37d50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
37d60 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
37d70 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
37d80 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
37d90 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
37da0 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
37db0 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
37dc0 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
37dd0 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
37de0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
37df0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
37e00 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
37e10 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
37e20 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
37e30 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
37e40 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
37e50 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
37e60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
37e70 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
37e80 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
37e90 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
37ea0 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
37eb0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
37ec0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
37ed0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
37ee0 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
37ef0 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
37f00 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
37f10 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
37f20 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
37f30 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
37f40 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
37f50 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
37f60 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
37f70 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
37f80 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
37f90 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
37fa0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
37fb0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
37fc0 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
37fd0 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
37fe0 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
37ff0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
38000 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
38010 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
38020 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
38030 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
38040 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
38050 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
38060 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
38070 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
38080 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
38090 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
380a0 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
380b0 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
380c0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
380d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
380e0 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
380f0 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
38100 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
38110 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
38120 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
38130 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
38140 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
38150 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
38160 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
38170 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
38180 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
38190 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
381a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
381b0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
381c0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
381d0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
381e0 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
381f0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
38200 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
38210 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
38220 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
38230 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
38240 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
38250 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
38260 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
38270 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
38280 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
38290 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
382a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
382b0 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
382c0 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
382d0 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
382e0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
382f0 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
38300 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
38310 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
38320 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
38330 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
38340 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
38350 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
38360 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
38370 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
38380 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
38390 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
383a0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
383b0 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
383c0 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
383d0 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
383e0 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
383f0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
38400 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
38410 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
38420 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
38430 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
38440 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
38450 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
38460 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
38470 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
38480 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
38490 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
384a0 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
384b0 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
384c0 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
384d0 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
384e0 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
384f0 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
38500 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
38510 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
38520 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
38530 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
38540 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
38550 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
38560 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
38570 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
38580 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
38590 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
385a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
385b0 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
385c0 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
385d0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
385e0 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
385f0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
38600 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
38610 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
38620 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20  eate_function(. 
38630 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
38640 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
38650 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
38660 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
38670 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
38680 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
38690 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
386a0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
386b0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
386c0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
386d0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
386e0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
386f0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
38700 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
38710 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  ext*).);.SQLITE_
38720 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
38730 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
38740 36 28 0a 20 2