System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact e7c26a7be3e431dd06898f8d262c4ef240c07366:


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 35 2e 31 2e 20 20  ersion 3.15.1.  
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 35 2e 31 22          "3.15.1"
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 35 30 30 31 0a 23 64 65 66 69 6e 65 20 53  015001.#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 31 2d 30 34       "2016-11-04
38a0: 20 31 32 3a 30 38 3a 34 39 20 31 31 33 36 38 36   12:08:49 113686
38b0: 33 63 37 36 35 37 36 31 31 30 65 37 31 30 64 64  3c76576110e710dd
38c0: 35 64 36 39 61 62 36 62 66 33 34 37 63 36 35 65  5d69ab6bf347c65e
38d0: 33 36 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  36"../*.** 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 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  on, sqlite3_sour
3930: 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ceid.**.** These
3940: 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76   interfaces prov
3950: 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66  ide the same inf
3960: 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20  ormation as the 
3970: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d  [SQLITE_VERSION]
3980: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  ,.** [SQLITE_VER
3990: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e  SION_NUMBER], an
39a0: 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  d [SQLITE_SOURCE
39b0: 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73  _ID] C preproces
39c0: 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75  sor macros.** bu
39d0: 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64  t are associated
39e0: 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72   with the librar
39f0: 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  y instead of the
3a00: 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e   header file.  ^
3a10: 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f  (Cautious.** pro
3a20: 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69  grammers might i
3a30: 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20  nclude assert() 
3a40: 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
3a50: 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  eir application 
3a60: 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61  to.** verify tha
3a70: 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  t values returne
3a80: 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72  d by these inter
3a90: 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20  faces match the 
3aa0: 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65  macros in.** the
3ab0: 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75   header, and thu
3ac0: 73 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  s ensure that th
3ad0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
3ae0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
3af0: 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61  h matching libra
3b00: 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69  ry and header fi
3b10: 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  les..**.** <bloc
3b20: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
3b30: 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f  assert( sqlite3_
3b40: 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65  libversion_numbe
3b50: 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53  r()==SQLITE_VERS
3b60: 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a  ION_NUMBER );.**
3b70: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
3b80: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
3b90: 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45  (),SQLITE_SOURCE
3ba0: 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73  _ID)==0 );.** as
3bb0: 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c  sert( strcmp(sql
3bc0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
3bd0: 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  ),SQLITE_VERSION
3be0: 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65  )==0 );.** </pre
3bf0: 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
3c00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
3c10: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
3c20: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f  ring constant co
3c30: 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20  ntains the text 
3c40: 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  of [SQLITE_VERSI
3c50: 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e  ON].** macro.  ^
3c60: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
3c70: 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f  ersion() functio
3c80: 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  n returns a poin
3c90: 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f  ter to the.** to
3ca0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72   the sqlite3_ver
3cb0: 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f  sion[] string co
3cc0: 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c  nstant.  The sql
3cd0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28  ite3_libversion(
3ce0: 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ).** function is
3cf0: 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73   provided for us
3d00: 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20  e in DLLs since 
3d10: 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c  DLL users usuall
3d20: 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a  y do not have.**
3d30: 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74   direct access t
3d40: 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  o string constan
3d50: 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c  ts within the DL
3d60: 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  L.  ^The.** sqli
3d70: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
3d80: 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e  umber() function
3d90: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
3da0: 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20  ger equal to.** 
3db0: 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f  [SQLITE_VERSION_
3dc0: 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73  NUMBER].  ^The s
3dd0: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
3de0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
3df0: 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ns .** a pointer
3e00: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e   to a string con
3e10: 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75  stant whose valu
3e20: 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73  e is the same as
3e30: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
3e40: 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72  _SOURCE_ID] C pr
3e50: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
3e60: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
3e70: 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f  : [sqlite_versio
3e80: 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
3e90: 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a  _source_id()]..*
3ea0: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
3eb0: 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f  st char sqlite3_
3ec0: 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49  version[] = SQLI
3ed0: 54 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49  TE_VERSION;.SQLI
3ee0: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
3ef0: 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  r *sqlite3_libve
3f00: 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c  rsion(void);.SQL
3f10: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
3f20: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
3f30: 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49  ceid(void);.SQLI
3f40: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
3f50: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
3f60: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  mber(void);../*.
3f70: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
3f80: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f  -Time Library Co
3f90: 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  mpilation Option
3fa0: 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a  s Diagnostics.**
3fb0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3fc0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
3fd0: 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  sed() function r
3fe0: 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a  eturns 0 or 1 .*
3ff0: 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65  * indicating whe
4000: 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69  ther the specifi
4010: 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65  ed option was de
4020: 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d  fined at .** com
4030: 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65  pile time.  ^The
4040: 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20   SQLITE_ prefix 
4050: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66  may be omitted f
4060: 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69  rom the .** opti
4070: 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74  on name passed t
4080: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  o sqlite3_compil
4090: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20  eoption_used(). 
40a0: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
40b0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
40c0: 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f  on_get() functio
40d0: 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69  n allows iterati
40e0: 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c  ng.** over the l
40f0: 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74  ist of options t
4100: 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64  hat were defined
4110: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
4120: 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67   by.** returning
4130: 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c   the N-th compil
4140: 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74  e time option st
4150: 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20  ring.  ^If N is 
4160: 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a  out of range,.**
4170: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
4180: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74  option_get() ret
4190: 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
41a0: 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ter.  ^The SQLIT
41b0: 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73  E_ .** prefix is
41c0: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e   omitted from an
41d0: 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  y strings return
41e0: 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
41f0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
4200: 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75  get()..**.** ^Su
4210: 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69  pport for the di
4220: 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f  agnostic functio
4230: 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ns sqlite3_compi
4240: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a  leoption_used().
4250: 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
4260: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
4270: 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  () may be omitte
4280: 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20  d by specifying 
4290: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
42a0: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
42b0: 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e  ON_DIAGS] option
42c0: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
42d0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
42e0: 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  : SQL functions 
42f0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
4300: 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e  ption_used()] an
4310: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  d.** [sqlite_com
4320: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
4330: 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69  ] and the [compi
4340: 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d  le_options pragm
4350: 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  a]..*/.#ifndef S
4360: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49  QLITE_OMIT_COMPI
4370: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53  LEOPTION_DIAGS.S
4380: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
4390: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
43a0: 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63  ion_used(const c
43b0: 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a  har *zOptName);.
43c0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
43d0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
43e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
43f0: 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a  (int N);.#endif.
4400: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4410: 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20   Test To See If 
4420: 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54  The Library Is T
4430: 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20  hreadsafe.**.** 
4440: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72  ^The sqlite3_thr
4450: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
4460: 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20  on returns zero 
4470: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
4480: 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d  * SQLite was com
4490: 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78  piled with mutex
44a0: 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64  ing code omitted
44b0: 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b   due to the.** [
44c0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
44d0: 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
44e0: 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74  option being set
44f0: 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c   to 0..**.** SQL
4500: 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69  ite can be compi
4510: 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68  led with or with
4520: 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68  out mutexes.  Wh
4530: 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  en.** the [SQLIT
4540: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20  E_THREADSAFE] C 
4550: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
4560: 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75  ro is 1 or 2, mu
4570: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
4580: 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20  bled and SQLite 
4590: 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  is threadsafe.  
45a0: 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  When the.** [SQL
45b0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
45c0: 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20  macro is 0, .** 
45d0: 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20  the mutexes are 
45e0: 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75  omitted.  Withou
45f0: 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69  t the mutexes, i
4600: 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a  t is not safe.**
4610: 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63   to use SQLite c
4620: 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d  oncurrently from
4630: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74   more than one t
4640: 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61  hread..**.** Ena
4650: 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e  bling mutexes in
4660: 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c  curs a measurabl
4670: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65  e performance pe
4680: 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20  nalty..** So if 
4690: 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f  speed is of utmo
46a0: 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69  st importance, i
46b0: 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f  t makes sense to
46c0: 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20   disable.** the 
46d0: 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f  mutexes.  But fo
46e0: 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79  r maximum safety
46f0: 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64  , mutexes should
4700: 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   be enabled..** 
4710: 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68  ^The default beh
4720: 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74  avior is for mut
4730: 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c  exes to be enabl
4740: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ed..**.** This i
4750: 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
4760: 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69  used by an appli
4770: 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73  cation to make s
4780: 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
4790: 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74  version of SQLit
47a0: 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e  e that it is lin
47b0: 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73  king against was
47c0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
47d0: 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65  * the desired se
47e0: 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51  tting of the [SQ
47f0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
4800: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68   macro..**.** Th
4810: 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c  is interface onl
4820: 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65  y reports on the
4830: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75   compile-time mu
4840: 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f  tex setting.** o
4850: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  f the [SQLITE_TH
4860: 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20  READSAFE] flag. 
4870: 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
4880: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53  mpiled with.** S
4890: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
48a0: 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75  =1 or =2 then mu
48b0: 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65  texes are enable
48c0: 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74  d by default but
48d0: 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79  .** can be fully
48e0: 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69   or partially di
48f0: 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63  sabled using a c
4900: 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
4910: 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74  config()].** wit
4920: 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c  h the verbs [SQL
4930: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
4940: 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54  ETHREAD], [SQLIT
4950: 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
4960: 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51  READ],.** or [SQ
4970: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
4980: 41 4c 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20  ALIZED].  ^(The 
4990: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
49a0: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74  the.** sqlite3_t
49b0: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
49c0: 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20  tion shows only 
49d0: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
49e0: 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74   setting of.** t
49f0: 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f  hread safety, no
4a00: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
4a10: 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73  hanges to that s
4a20: 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a  etting made by.*
4a30: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  * sqlite3_config
4a40: 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  (). In other wor
4a50: 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ds, the return v
4a60: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
4a70: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a  3_threadsafe().*
4a80: 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62  * is unchanged b
4a90: 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  y calls to sqlit
4aa0: 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a  e3_config().)^.*
4ab0: 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  *.** See the [th
4ac0: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
4ad0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
4ae0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
4af0: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  mation..*/.SQLIT
4b00: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
4b10: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
4b20: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
4b30: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
4b40: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a  nnection Handle.
4b50: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61  ** KEYWORDS: {da
4b60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4b70: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  n} {database con
4b80: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  nections}.**.** 
4b90: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65  Each open SQLite
4ba0: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70   database is rep
4bb0: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f  resented by a po
4bc0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
4bd0: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  ance of.** the o
4be0: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
4bf0: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e  named "sqlite3".
4c00: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74    It is useful t
4c10: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71  o think of an sq
4c20: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72  lite3.** pointer
4c30: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20   as an object.  
4c40: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
4c50: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
4c60: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
4c70: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
4c80: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
4c90: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63  are its construc
4ca0: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74  tors, and [sqlit
4cb0: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61  e3_close()].** a
4cc0: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
4cd0: 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20  e_v2()] are its 
4ce0: 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68  destructors.  Th
4cf0: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
4d00: 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  er.** interfaces
4d10: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71   (such as.** [sq
4d20: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
4d30: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
4d40: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
4d50: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
4d60: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
4d70: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68  ] to name but th
4d80: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65  ree) that are me
4d90: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73  thods on an.** s
4da0: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a  qlite3 object..*
4db0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
4dc0: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
4dd0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
4de0: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
4df0: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  r Types.** KEYWO
4e00: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
4e10: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
4e20: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
4e30: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
4e40: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
4e50: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
4e60: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
4e70: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
4e80: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
4e90: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
4ea0: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
4eb0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
4ec0: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
4ed0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
4ee0: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
4ef0: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ype definitions.
4f00: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69  .** The sqlite_i
4f10: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
4f20: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65  uint64 types are
4f30: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
4f40: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
4f50: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a  atibility only..
4f60: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
4f70: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
4f80: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20  ite_int64 types 
4f90: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
4fa0: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  r values.** betw
4fb0: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38  een -92233720368
4fc0: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32  54775808 and +92
4fd0: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
4fe0: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54  7 inclusive.  ^T
4ff0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69  he.** sqlite3_ui
5000: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
5010: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  uint64 types can
5020: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
5030: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65  alues .** betwee
5040: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34  n 0 and +1844674
5050: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e  4073709551615 in
5060: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64  clusive..*/.#ifd
5070: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
5080: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
5090: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
50a0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
50b0: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
50c0: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
50d0: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
50e0: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
50f0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
5100: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
5110: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
5120: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
5130: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
5140: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
5150: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
5160: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
5170: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
5180: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
5190: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
51a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
51b0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
51c0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
51d0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
51e0: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
51f0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
5200: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
5210: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
5220: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
5230: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
5240: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
5250: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
5260: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
5270: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
5280: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
5290: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
52a0: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
52b0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
52c0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
52d0: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
52e0: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
52f0: 74 69 6f 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54  tion.** DESTRUCT
5300: 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
5310: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
5320: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
5330: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f  e3_close_v2() ro
5340: 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 74 72  utines are destr
5350: 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68  uctors.** for th
5360: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
5370: 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  ct..** ^Calls to
5380: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
5390: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f   and sqlite3_clo
53a0: 73 65 5f 76 32 28 29 20 72 65 74 75 72 6e 20 5b  se_v2() return [
53b0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a  SQLITE_OK] if.**
53c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
53d0: 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73 73  bject is success
53e0: 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64 20  fully destroyed 
53f0: 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61 74  and all associat
5400: 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73 20  ed.** resources 
5410: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
5420: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  .**.** ^If the d
5430: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
5440: 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  on is associated
5450: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
5460: 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  d prepared.** st
5470: 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69  atements or unfi
5480: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
5490: 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74 68  ackup objects th
54a0: 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  en sqlite3_close
54b0: 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65  ().** will leave
54c0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
54d0: 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e  nnection open an
54e0: 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
54f0: 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73  _BUSY]..** ^If s
5500: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
5510: 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
5520: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
5530: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
5540: 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e  .** and/or unfin
5550: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
5560: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20  ckups, then the 
5570: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
5580: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61  ion becomes.** a
5590: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62  n unusable "zomb
55a0: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61  ie" which will a
55b0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20  utomatically be 
55c0: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
55d0: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65   the.** last pre
55e0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
55f0: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20  is finalized or 
5600: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
5610: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69  _backup is.** fi
5620: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c  nished.  The sql
5630: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
5640: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
5650: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69  ended for use wi
5660: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75  th.** host langu
5670: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61  ages that are ga
5680: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c  rbage collected,
5690: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f   and where the o
56a0: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a  rder in which.**
56b0: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65   destructors are
56c0: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74   called is arbit
56d0: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  rary..**.** Appl
56e0: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
56f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
5700: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
5710: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
5720: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c  ements],.** [sql
5730: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
5740: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
5750: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
5760: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61   .** [sqlite3_ba
5770: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69  ckup_finish | fi
5780: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74  nish] all [sqlit
5790: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
57a0: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
57b0: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
57c0: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
57d0: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
57e0: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
57f0: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69  ct.  ^If.** sqli
5800: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
5810: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
5820: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
5830: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
5840: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
5850: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
5860: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
5870: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
5880: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
5890: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
58a0: 20 69 74 20 72 65 74 75 72 6e 73 20 5b 53 51 4c   it returns [SQL
58b0: 49 54 45 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20  ITE_OK] and the 
58c0: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
58d0: 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20  of resources is 
58e0: 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61  deferred until a
58f0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
5900: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
5910: 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64  handles],.** and
5920: 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70   [sqlite3_backup
5930: 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c  ] objects are al
5940: 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  so destroyed..**
5950: 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69  .** ^If an [sqli
5960: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64  te3] object is d
5970: 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61  estroyed while a
5980: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
5990: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
59a0: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
59b0: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
59c0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
59d0: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
59e0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
59f0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
5a00: 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20  close_v2(C)].** 
5a10: 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
5a20: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
5a30: 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d   or an [sqlite3]
5a40: 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20   object pointer 
5a50: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
5a60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
5a70: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
5a80: 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
5a90: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
5aa0: 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f  , and not previo
5ab0: 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20  usly closed..** 
5ac0: 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
5ad0: 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69  _close() or sqli
5ae0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77  te3_close_v2() w
5af0: 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
5b00: 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  er.** argument i
5b10: 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
5b20: 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  op..*/.SQLITE_AP
5b30: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  I int sqlite3_cl
5b40: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53  ose(sqlite3*);.S
5b50: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
5b60: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73  lite3_close_v2(s
5b70: 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
5b80: 20 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20   The type for a 
5b90: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
5ba0: 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65  n..** This is le
5bb0: 67 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61  gacy and depreca
5bc0: 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c  ted.  It is incl
5bd0: 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  uded for histori
5be0: 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  cal.** compatibi
5bf0: 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  lity and is not 
5c00: 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74  documented..*/.t
5c10: 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c  ypedef int (*sql
5c20: 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76  ite3_callback)(v
5c30: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
5c40: 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a   char**);../*.**
5c50: 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53   CAPI3REF: One-S
5c60: 74 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74  tep Query Execut
5c70: 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a  ion Interface.**
5c80: 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
5c90: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
5ca0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
5cb0: 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69  ace is a conveni
5cc0: 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f  ence wrapper aro
5cd0: 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
5ce0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
5cf0: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
5d00: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69   and [sqlite3_fi
5d10: 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68  nalize()],.** th
5d20: 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70  at allows an app
5d30: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20  lication to run 
5d40: 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65  multiple stateme
5d50: 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69  nts of SQL.** wi
5d60: 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20  thout having to 
5d70: 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63  use a lot of C c
5d80: 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode. .**.** ^The
5d90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
5da0: 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a  interface runs z
5db0: 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d  ero or more UTF-
5dc0: 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65  8 encoded,.** se
5dd0: 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
5de0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
5df0: 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20  passed into its 
5e00: 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a  2nd argument,.**
5e10: 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20   in the context 
5e20: 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
5e30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73   connection] pas
5e40: 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73  sed in as its 1s
5e50: 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20  t.** argument.  
5e60: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
5e70: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65   function of the
5e80: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
5e90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
5ea0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  () is not NULL, 
5eb0: 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b  then it is invok
5ec0: 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75  ed for each resu
5ed0: 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67  lt row.** coming
5ee0: 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c   out of the eval
5ef0: 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  uated SQL statem
5f00: 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20  ents.  ^The 4th 
5f10: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
5f20: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
5f30: 20 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68   relayed through
5f40: 20 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75   to the 1st argu
5f50: 6d 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20  ment of each.** 
5f60: 63 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74  callback invocat
5f70: 69 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ion.  ^If the ca
5f80: 6c 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74  llback pointer t
5f90: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
5fa0: 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  .** is NULL, the
5fb0: 6e 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73  n no callback is
5fc0: 20 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e   ever invoked an
5fd0: 64 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72  d result rows ar
5fe0: 65 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  e.** ignored..**
5ff0: 0a 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72  .** ^If an error
6000: 20 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76   occurs while ev
6010: 61 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c  aluating the SQL
6020: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
6030: 65 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  ed into.** sqlit
6040: 65 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20  e3_exec(), then 
6050: 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65  execution of the
6060: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65   current stateme
6070: 6e 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20  nt stops and.** 
6080: 73 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65  subsequent state
6090: 6d 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65  ments are skippe
60a0: 64 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20  d.  ^If the 5th 
60b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
60c0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
60d0: 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
60e0: 61 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67  any error messag
60f0: 65 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  e is written int
6100: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
6110: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
6120: 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64  e3_malloc()] and
6130: 20 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72   passed back thr
6140: 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72  ough the 5th par
6150: 61 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76  ameter..** To av
6160: 6f 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73  oid memory leaks
6170: 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
6180: 6e 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20  n should invoke 
6190: 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
61a0: 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73  .** on error mes
61b0: 73 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74  sage strings ret
61c0: 75 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68  urned through th
61d0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
61e0: 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  of.** sqlite3_ex
61f0: 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65  ec() after the e
6200: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
6210: 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ing is no longer
6220: 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20   needed..** ^If 
6230: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
6240: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
6250: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  c() is not NULL 
6260: 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  and no errors.**
6270: 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c   occur, then sql
6280: 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73  ite3_exec() sets
6290: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   the pointer in 
62a0: 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65  its 5th paramete
62b0: 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66  r to.** NULL bef
62c0: 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
62d0: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69  *.** ^If an sqli
62e0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
62f0: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
6300: 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65  zero, the sqlite
6310: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74  3_exec().** rout
6320: 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ine returns SQLI
6330: 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74  TE_ABORT without
6340: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61   invoking the ca
6350: 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64  llback again and
6360: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e  .** without runn
6370: 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65  ing any subseque
6380: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
6390: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e  s..**.** ^The 2n
63a0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
63b0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
63c0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
63d0: 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  on is the.** num
63e0: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
63f0: 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e  n the result.  ^
6400: 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  The 3rd argument
6410: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
6420: 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61  exec().** callba
6430: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
6440: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
6450: 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61  rings obtained a
6460: 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  s if from.** [sq
6470: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
6480: 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61  t()], one for ea
6490: 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20  ch column.  ^If 
64a0: 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a  an element of a.
64b0: 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73  ** result row is
64c0: 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
64d0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72  orresponding str
64e0: 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ing pointer for 
64f0: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
6500: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
6510: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
6520: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
6530: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73  ment to the.** s
6540: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
6550: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
6560: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
6570: 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20  o strings where 
6580: 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65  each.** entry re
6590: 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d  presents the nam
65a0: 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69  e of correspondi
65b0: 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ng result column
65c0: 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20   as obtained.** 
65d0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
65e0: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a  lumn_name()]..**
65f0: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20  .** ^If the 2nd 
6600: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
6610: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61  ite3_exec() is a
6620: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61   NULL pointer, a
6630: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61   pointer.** to a
6640: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
6650: 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61  or a pointer tha
6660: 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20  t contains only 
6670: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f  whitespace and/o
6680: 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e  r .** SQL commen
6690: 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20  ts, then no SQL 
66a0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
66b0: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65  valuated and the
66c0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
66d0: 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  not changed..**.
66e0: 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a  ** Restrictions:
66f0: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
6700: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
6710: 69 6f 6e 20 6d 75 73 74 20 65 6e 73 75 72 65 20  ion must ensure 
6720: 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72  that the 1st par
6730: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
6740: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20  3_exec().**     
6750: 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20   is a valid and 
6760: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
6770: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c  onnection]..** <
6780: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
6790: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ion must not clo
67a0: 73 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  se the [database
67b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65   connection] spe
67c0: 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20  cified by.**    
67d0: 20 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65    the 1st parame
67e0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
67f0: 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69  xec() while sqli
6800: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75  te3_exec() is ru
6810: 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  nning..** <li> T
6820: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
6830: 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74  ust not modify t
6840: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
6850: 20 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74   text passed int
6860: 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e  o.**      the 2n
6870: 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73  d parameter of s
6880: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68  qlite3_exec() wh
6890: 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  ile sqlite3_exec
68a0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  () is running..*
68b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54  * </ul>.*/.SQLIT
68c0: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
68d0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
68e0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
68f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6900: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
6910: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
6920: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst 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 20 2f 2a 20 53 51 4c 20           /* SQL 
6950: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
6960: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
6970: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
6980: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
6990: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
69a0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
69b0: 2c 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 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
69e0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
69f0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
6a00: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
6a10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6a20: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
6a30: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
6a40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6a50: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  : Result Codes.*
6a60: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73  * KEYWORDS: {res
6a70: 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74  ult code definit
6a80: 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  ions}.**.** Many
6a90: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
6aa0: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
6ab0: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
6ac0: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
6ad0: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72  wn.** here in or
6ae0: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20  der to indicate 
6af0: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
6b00: 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72  re..**.** New er
6b10: 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65  ror codes may be
6b20: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
6b30: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
6b40: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ite..**.** See a
6b50: 6c 73 6f 3a 20 5b 65 78 74 65 6e 64 65 64 20 72  lso: [extended r
6b60: 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e  esult code defin
6b70: 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69  itions].*/.#defi
6b80: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
6b90: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
6ba0: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
6bb0: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
6bc0: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
6bd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6be0: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
6bf0: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
6c00: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
6c10: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
6c20: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
6c30: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
6c40: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
6c50: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
6c60: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
6c70: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
6c80: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
6c90: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
6ca0: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
6cb0: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
6cc0: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
6cd0: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
6ce0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6cf0: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
6d00: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
6d10: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
6d20: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
6d30: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
6d40: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
6d50: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
6d60: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
6d70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
6d80: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
6d90: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
6da0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
6db0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
6dc0: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
6dd0: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
6de0: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
6df0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6e00: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
6e10: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
6e20: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
6e30: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
6e40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6e50: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
6e60: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
6e70: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
6e80: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
6e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
6ea0: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
6eb0: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
6ec0: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
6ed0: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
6ee0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
6ef0: 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f     12   /* Unkno
6f00: 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c  wn opcode in sql
6f10: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
6f20: 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  l() */.#define S
6f30: 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20  QLITE_FULL      
6f40: 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74    13   /* Insert
6f50: 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75  ion failed becau
6f60: 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66  se database is f
6f70: 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ull */.#define S
6f80: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20  QLITE_CANTOPEN  
6f90: 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65    14   /* Unable
6fa0: 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
6fb0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
6fc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f  efine SQLITE_PRO
6fd0: 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a  TOCOL    15   /*
6fe0: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70   Database lock p
6ff0: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f  rotocol error */
7000: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7010: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20  EMPTY       16  
7020: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20   /* Database is 
7030: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65  empty */.#define
7040: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20   SQLITE_SCHEMA  
7050: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20      17   /* The 
7060: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
7070: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69  changed */.#defi
7080: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47  ne SQLITE_TOOBIG
7090: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74        18   /* St
70a0: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63  ring or BLOB exc
70b0: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20  eeds size limit 
70c0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
70d0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39  E_CONSTRAINT  19
70e0: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20     /* Abort due 
70f0: 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69  to constraint vi
7100: 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69  olation */.#defi
7110: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54  ne SQLITE_MISMAT
7120: 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61  CH    20   /* Da
7130: 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68  ta type mismatch
7140: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
7150: 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32  TE_MISUSE      2
7160: 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75  1   /* Library u
7170: 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  sed incorrectly 
7180: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
7190: 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32  E_NOLFS       22
71a0: 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65     /* Uses OS fe
71b0: 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f  atures not suppo
71c0: 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a  rted on host */.
71d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
71e0: 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20  UTH        23   
71f0: 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  /* Authorization
7200: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
7210: 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54  ne SQLITE_FORMAT
7220: 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75        24   /* Au
7230: 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65  xiliary database
7240: 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f   format error */
7250: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7260: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20  RANGE       25  
7270: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65   /* 2nd paramete
7280: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
7290: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a  d out of range *
72a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
72b0: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20  _NOTADB      26 
72c0: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64    /* File opened
72d0: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64   that is not a d
72e0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
72f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
7300: 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20  OTICE      27   
7310: 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73  /* Notifications
7320: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
7330: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
7340: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20  QLITE_WARNING   
7350: 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e    28   /* Warnin
7360: 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  gs from sqlite3_
7370: 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  log() */.#define
7380: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
7390: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
73a0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
73b0: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
73c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
73d0: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
73e0: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
73f0: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
7400: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
7410: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
7420: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
7430: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
7440: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
7450: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78  ** KEYWORDS: {ex
7460: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
7470: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a  de definitions}.
7480: 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20 64 65 66  **.** In its def
7490: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
74a0: 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50 49 20 72  on, SQLite API r
74b0: 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 6f  outines return o
74c0: 6e 65 20 6f 66 20 33 30 20 69 6e 74 65 67 65 72  ne of 30 integer
74d0: 0a 2a 2a 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  .** [result code
74e0: 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78  s].  However, ex
74f0: 70 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f  perience has sho
7500: 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a  wn that many of.
7510: 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20  ** these result 
7520: 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f  codes are too co
7530: 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54  arse-grained.  T
7540: 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69  hey do not provi
7550: 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e  de as.** much in
7560: 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
7570: 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67  problems as prog
7580: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69  rammers might li
7590: 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72  ke.  In an effor
75a0: 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20  t to.** address 
75b0: 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73  this, newer vers
75c0: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28  ions of SQLite (
75d0: 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 5b 64  version 3.3.8 [d
75e0: 61 74 65 6f 66 3a 33 2e 33 2e 38 5d 0a 2a 2a 20  ateof:3.3.8].** 
75f0: 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75  and later) inclu
7600: 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f  de.** support fo
7610: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73  r additional res
7620: 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70  ult codes that p
7630: 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61  rovide more deta
7640: 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  iled information
7650: 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73  .** about errors
7660: 2e 20 54 68 65 73 65 20 5b 65 78 74 65 6e 64 65  . These [extende
7670: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
7680: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  are enabled or d
7690: 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20  isabled.** on a 
76a0: 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  per database con
76b0: 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73  nection basis us
76c0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
76d0: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
76e0: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49  ult_codes()] API
76f0: 2e 20 20 4f 72 2c 20 74 68 65 20 65 78 74 65 6e  .  Or, the exten
7700: 64 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a 2a 20  ded code for.** 
7710: 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
7720: 65 72 72 6f 72 20 63 61 6e 20 62 65 20 6f 62 74  error can be obt
7730: 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  ained using.** [
7740: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
7750: 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a 2f 0a  _errcode()]..*/.
7760: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7770: 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20 20  OERR_READ       
7780: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7790: 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OERR | (1<<8)).#
77a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
77b0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 20  ERR_SHORT_READ  
77c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
77d0: 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ERR | (2<<8)).#d
77e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
77f0: 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20 20  RR_WRITE        
7800: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
7810: 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  RR | (3<<8)).#de
7820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7830: 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20 20  R_FSYNC         
7840: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7850: 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  R | (4<<8)).#def
7860: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7870: 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20 20  _DIR_FSYNC      
7880: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7890: 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69   | (5<<8)).#defi
78a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
78b0: 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20 20  TRUNCATE        
78c0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
78d0: 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (6<<8)).#defin
78e0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46  e SQLITE_IOERR_F
78f0: 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20 20  STAT            
7900: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7910: 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (7<<8)).#define
7920: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55 4e   SQLITE_IOERR_UN
7930: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
7940: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
7950: 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (8<<8)).#define 
7960: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44 4c  SQLITE_IOERR_RDL
7970: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 28  OCK            (
7980: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
7990: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
79a0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
79b0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28 53  TE            (S
79c0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
79d0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
79e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
79f0: 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28 53  KED           (S
7a00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
7a10: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
7a20: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d 45  QLITE_IOERR_NOME
7a30: 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  M             (S
7a40: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
7a50: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
7a60: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43 45  QLITE_IOERR_ACCE
7a70: 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28 53  SS            (S
7a80: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
7a90: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
7aa0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45 43  QLITE_IOERR_CHEC
7ab0: 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28 53  KRESERVEDLOCK (S
7ac0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
7ad0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
7ae0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43 4b  QLITE_IOERR_LOCK
7af0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
7b00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
7b10: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
7b20: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f 53  QLITE_IOERR_CLOS
7b30: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  E             (S
7b40: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
7b50: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
7b60: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
7b70: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28 53  CLOSE         (S
7b80: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
7b90: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
7ba0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4f  QLITE_IOERR_SHMO
7bb0: 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28 53  PEN           (S
7bc0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
7bd0: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
7be0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 53  QLITE_IOERR_SHMS
7bf0: 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28 53  IZE           (S
7c00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
7c10: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
7c20: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4c  QLITE_IOERR_SHML
7c30: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28 53  OCK           (S
7c40: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
7c50: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
7c60: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d 4d  QLITE_IOERR_SHMM
7c70: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AP            (S
7c80: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
7c90: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
7ca0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45 4b  QLITE_IOERR_SEEK
7cb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
7cc0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
7cd0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
7ce0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c 45  QLITE_IOERR_DELE
7cf0: 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28 53  TE_NOENT      (S
7d00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
7d10: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
7d20: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d 41 50  QLITE_IOERR_MMAP
7d30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
7d40: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
7d50: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
7d60: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45 54 54  QLITE_IOERR_GETT
7d70: 45 4d 50 50 41 54 48 20 20 20 20 20 20 20 28 53  EMPPATH       (S
7d80: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
7d90: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
7da0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f 4e 56  QLITE_IOERR_CONV
7db0: 50 41 54 48 20 20 20 20 20 20 20 20 20 20 28 53  PATH          (S
7dc0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
7dd0: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
7de0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 56 4e 4f 44  QLITE_IOERR_VNOD
7df0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  E             (S
7e00: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
7e10: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
7e20: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 55 54 48  QLITE_IOERR_AUTH
7e30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
7e40: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
7e50: 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  8<<8)).#define S
7e60: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48 41  QLITE_LOCKED_SHA
7e70: 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28 53  REDCACHE      (S
7e80: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20 20  QLITE_LOCKED |  
7e90: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
7ea0: 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43 4f  SQLITE_BUSY_RECO
7eb0: 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20 28  VERY           (
7ec0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c 20  SQLITE_BUSY   | 
7ed0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
7ee0: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53 4e 41   SQLITE_BUSY_SNA
7ef0: 50 53 48 4f 54 20 20 20 20 20 20 20 20 20 20 20  PSHOT           
7f00: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
7f10: 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (2<<8)).#defin
7f20: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
7f30: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
7f40: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
7f50: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
7f60: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
7f70: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20  PEN_ISDIR       
7f80: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
7f90: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  PEN | (2<<8)).#d
7fa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
7fb0: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20  TOPEN_FULLPATH  
7fc0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
7fd0: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a  TOPEN | (3<<8)).
7fe0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
7ff0: 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41 54 48  ANTOPEN_CONVPATH
8000: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
8010: 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c 38 29  ANTOPEN | (4<<8)
8020: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
8030: 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20  _CORRUPT_VTAB   
8040: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
8050: 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38  _CORRUPT | (1<<8
8060: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
8070: 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56  E_READONLY_RECOV
8080: 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54  ERY       (SQLIT
8090: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c  E_READONLY | (1<
80a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
80b0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e  ITE_READONLY_CAN
80c0: 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c  TLOCK       (SQL
80d0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
80e0: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
80f0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
8100: 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 28 53  OLLBACK       (S
8110: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
8120: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
8130: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
8140: 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20 20 20  _DBMOVED        
8150: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
8160: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
8170: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f  ne SQLITE_ABORT_
8180: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20  ROLLBACK        
8190: 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20    (SQLITE_ABORT 
81a0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
81b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
81c0: 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20 20  INT_CHECK       
81d0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
81e0: 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  INT | (1<<8)).#d
81f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
8200: 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48 4f  STRAINT_COMMITHO
8210: 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  OK   (SQLITE_CON
8220: 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38 29  STRAINT | (2<<8)
8230: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
8240: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52 45  _CONSTRAINT_FORE
8250: 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54 45  IGNKEY   (SQLITE
8260: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 33  _CONSTRAINT | (3
8270: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
8280: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
8290: 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53 51  FUNCTION     (SQ
82a0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
82b0: 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (4<<8)).#defin
82c0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
82d0: 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20 20  INT_NOTNULL     
82e0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
82f0: 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64  INT | (5<<8)).#d
8300: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
8310: 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59 4b  STRAINT_PRIMARYK
8320: 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e  EY   (SQLITE_CON
8330: 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38 29  STRAINT | (6<<8)
8340: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
8350: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49 47  _CONSTRAINT_TRIG
8360: 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 54 45  GER      (SQLITE
8370: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 37  _CONSTRAINT | (7
8380: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
8390: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
83a0: 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 53 51  UNIQUE       (SQ
83b0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
83c0: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
83d0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
83e0: 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  INT_VTAB        
83f0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
8400: 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  INT | (9<<8)).#d
8410: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
8420: 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20 20  STRAINT_ROWID   
8430: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
8440: 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38 29  STRAINT |(10<<8)
8450: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
8460: 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f  _NOTICE_RECOVER_
8470: 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54 45  WAL      (SQLITE
8480: 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38 29  _NOTICE | (1<<8)
8490: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
84a0: 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52 5f  _NOTICE_RECOVER_
84b0: 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54 45  ROLLBACK (SQLITE
84c0: 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38 29  _NOTICE | (2<<8)
84d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
84e0: 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e 44  _WARNING_AUTOIND
84f0: 45 58 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  EX       (SQLITE
8500: 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c 38  _WARNING | (1<<8
8510: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
8520: 45 5f 41 55 54 48 5f 55 53 45 52 20 20 20 20 20  E_AUTH_USER     
8530: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
8540: 45 5f 41 55 54 48 20 7c 20 28 31 3c 3c 38 29 29  E_AUTH | (1<<8))
8550: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8560: 4f 4b 5f 4c 4f 41 44 5f 50 45 52 4d 41 4e 45 4e  OK_LOAD_PERMANEN
8570: 54 4c 59 20 20 20 20 20 28 53 51 4c 49 54 45 5f  TLY     (SQLITE_
8580: 4f 4b 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a  OK | (1<<8))../*
8590: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
85a0: 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65  ags For File Ope
85b0: 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a  n Operations.**.
85c0: 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c  ** These bit val
85d0: 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  ues are intended
85e0: 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a   for use in the.
85f0: 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ** 3rd parameter
8600: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
8610: 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65  _open_v2()] inte
8620: 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20  rface and.** in 
8630: 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
8640: 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
8650: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
8660: 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  hod..*/.#define 
8670: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
8680: 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30  ONLY         0x0
8690: 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66  0000001  /* Ok f
86a0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
86b0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
86c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
86d0: 57 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30  WRITE        0x0
86e0: 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66  0000002  /* Ok f
86f0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
8700: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
8710: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
8720: 54 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30  TE           0x0
8730: 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66  0000004  /* Ok f
8740: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
8750: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
8760: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
8770: 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30  TEONCLOSE    0x0
8780: 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20  0000008  /* VFS 
8790: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
87a0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
87b0: 55 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30  USIVE        0x0
87c0: 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20  0000010  /* VFS 
87d0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
87e0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f  SQLITE_OPEN_AUTO
87f0: 50 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30  PROXY        0x0
8800: 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20  0000020  /* VFS 
8810: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
8820: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20  SQLITE_OPEN_URI 
8830: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
8840: 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66  0000040  /* Ok f
8850: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
8860: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
8870: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f  SQLITE_OPEN_MEMO
8880: 52 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30  RY           0x0
8890: 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66  0000080  /* Ok f
88a0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
88b0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
88c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
88d0: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
88e0: 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20  0000100  /* VFS 
88f0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
8900: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
8910: 5f 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30  _DB          0x0
8920: 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20  0000200  /* VFS 
8930: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
8940: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
8950: 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30  SIENT_DB     0x0
8960: 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20  0000400  /* VFS 
8970: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
8980: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
8990: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
89a0: 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20  0000800  /* VFS 
89b0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
89c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50  SQLITE_OPEN_TEMP
89d0: 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30  _JOURNAL     0x0
89e0: 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20  0001000  /* VFS 
89f0: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
8a00: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
8a10: 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30  OURNAL       0x0
8a20: 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20  0002000  /* VFS 
8a30: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
8a40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54  SQLITE_OPEN_MAST
8a50: 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30  ER_JOURNAL   0x0
8a60: 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20  0004000  /* VFS 
8a70: 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  only */.#define 
8a80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
8a90: 54 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30  TEX          0x0
8aa0: 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0008000  /* Ok f
8ab0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
8ac0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
8ad0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
8ae0: 4d 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30  MUTEX        0x0
8af0: 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0010000  /* Ok f
8b00: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
8b10: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
8b20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
8b30: 45 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30  EDCACHE      0x0
8b40: 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0020000  /* Ok f
8b50: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
8b60: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
8b70: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
8b80: 41 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30  ATECACHE     0x0
8b90: 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66  0040000  /* Ok f
8ba0: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
8bb0: 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  v2() */.#define 
8bc0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20  SQLITE_OPEN_WAL 
8bd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
8be0: 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20  0080000  /* VFS 
8bf0: 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65  only */../* Rese
8c00: 72 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20  rved:           
8c10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
8c20: 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a  00F00000 */../*.
8c30: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76  ** CAPI3REF: Dev
8c40: 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74  ice Characterist
8c50: 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44  ics.**.** The xD
8c60: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8c70: 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  tics method of t
8c80: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
8c90: 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63  ethods].** objec
8ca0: 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  t returns an int
8cb0: 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20  eger which is a 
8cc0: 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a  vector of these.
8cd0: 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78  ** bit values ex
8ce0: 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61  pressing I/O cha
8cf0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20  racteristics of 
8d00: 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65  the mass storage
8d10: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
8d20: 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74  holds the file t
8d30: 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
8d40: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
8d50: 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a  refers to..**.**
8d60: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8d70: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
8d80: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
8d90: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
8da0: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
8db0: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8dc0: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
8dd0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
8de0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
8df0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
8e00: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
8e10: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
8e20: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
8e30: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
8e40: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
8e50: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
8e60: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
8e70: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
8e80: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
8e90: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
8ea0: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
8eb0: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
8ec0: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
8ed0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
8ee0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
8ef0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
8f00: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
8f10: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
8f20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8f30: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
8f40: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
8f50: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
8f60: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
8f70: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
8f80: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
8f90: 72 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c  rite().  The SQL
8fa0: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
8fb0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72  AFE_OVERWRITE pr
8fc0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
8fd0: 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f  t.** after reboo
8fe0: 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72  t following a cr
8ff0: 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73  ash or power los
9000: 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65  s, the only byte
9010: 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74  s in a.** file t
9020: 68 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e  hat were written
9030: 20 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74   at the applicat
9040: 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20  ion level might 
9050: 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  have changed.** 
9060: 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e  and that adjacen
9070: 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79  t bytes, even by
9080: 74 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73  tes within the s
9090: 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a  ame sector are.*
90a0: 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  * guaranteed to 
90b0: 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54  be unchanged.  T
90c0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
90d0: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
90e0: 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e  _OPEN.** flag in
90f0: 64 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69  dicate that a fi
9100: 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c  le cannot be del
9110: 65 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20  eted when open. 
9120: 20 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49   The.** SQLITE_I
9130: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66  OCAP_IMMUTABLE f
9140: 6c 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68  lag indicates th
9150: 61 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f  at the file is o
9160: 6e 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d  n.** read-only m
9170: 65 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20  edia and cannot 
9180: 62 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20  be changed even 
9190: 62 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74  by processes wit
91a0: 68 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72  h.** elevated pr
91b0: 69 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65  ivileges..*/.#de
91c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
91d0: 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20  P_ATOMIC        
91e0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
91f0: 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  001.#define SQLI
9200: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
9210: 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20  12              
9220: 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69  0x00000002.#defi
9230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
9240: 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20  ATOMIC1K        
9250: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
9260: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
9270: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20  _IOCAP_ATOMIC2K 
9280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
9290: 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65  00000008.#define
92a0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
92b0: 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20  OMIC4K          
92c0: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a       0x00000010.
92d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
92e0: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20  OCAP_ATOMIC8K   
92f0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
9300: 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53  000020.#define S
9310: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
9320: 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20  IC16K           
9330: 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64     0x00000040.#d
9340: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
9350: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20  AP_ATOMIC32K    
9360: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
9370: 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0080.#define SQL
9380: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
9390: 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  64K             
93a0: 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66   0x00000100.#def
93b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
93c0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20  _SAFE_APPEND    
93d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
93e0: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
93f0: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
9400: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30  AL             0
9410: 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e  x00000400.#defin
9420: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
9430: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
9440: 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30  OPEN  0x00000800
9450: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9460: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
9470: 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30  OVERWRITE    0x0
9480: 30 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20  0001000.#define 
9490: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
94a0: 55 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  UTABLE          
94b0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a      0x00002000..
94c0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
94d0: 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76  File Locking Lev
94e0: 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  els.**.** SQLite
94f0: 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65   uses one of the
9500: 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  se integer value
9510: 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  s as the second.
9520: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  ** argument to c
9530: 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f  alls it makes to
9540: 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64   the xLock() and
9550: 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f   xUnlock() metho
9560: 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c  ds.** of an [sql
9570: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
9580: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66   object..*/.#def
9590: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
95a0: 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a  NONE          0.
95b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
95c0: 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20  OCK_SHARED      
95d0: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
95e0: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
95f0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
9600: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
9610: 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66  ING       3.#def
9620: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
9630: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a  EXCLUSIVE     4.
9640: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
9650: 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e   Synchronization
9660: 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a   Type Flags.**.*
9670: 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e  * When SQLite in
9680: 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28  vokes the xSync(
9690: 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a  ) method of an.*
96a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
96b0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74  thods] object it
96c0: 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74   uses a combinat
96d0: 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  ion of.** these 
96e0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
96f0: 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
9700: 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65  ument..**.** Whe
9710: 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  n the SQLITE_SYN
9720: 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20  C_DATAONLY flag 
9730: 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e  is used, it mean
9740: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79  s that the.** sy
9750: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c  nc operation onl
9760: 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68  y needs to flush
9770: 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74   data to mass st
9780: 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a  orage.  Inode.**
9790: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65   information nee
97a0: 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64  d not be flushed
97b0: 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66  . If the lower f
97c0: 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20  our bits of the 
97d0: 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51  flag.** equal SQ
97e0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
97f0: 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20  , that means to 
9800: 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  use normal fsync
9810: 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a  () semantics..**
9820: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
9830: 75 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51  ur bits equal SQ
9840: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
9850: 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f  that means.** to
9860: 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74   use Mac OS X st
9870: 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73  yle fullsync ins
9880: 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e  tead of fsync().
9890: 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f  .**.** Do not co
98a0: 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45  nfuse the SQLITE
98b0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
98c0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
98d0: 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20  L flags.** with 
98e0: 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  the [PRAGMA sync
98f0: 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20  hronous]=NORMAL 
9900: 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  and [PRAGMA sync
9910: 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a  hronous]=FULL.**
9920: 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20   settings.  The 
9930: 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61  [synchronous pra
9940: 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20  gma] determines 
9950: 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68  when calls to th
9960: 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d  e.** xSync VFS m
9970: 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20  ethod occur and 
9980: 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c  applies uniforml
9990: 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61  y across all pla
99a0: 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53  tforms..** The S
99b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
99c0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
99d0: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74  C_FULL flags det
99e0: 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e  ermine how.** en
99f0: 65 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72  ergetic or rigor
9a00: 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20  ous or forceful 
9a10: 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69  the sync operati
9a20: 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f  ons are and.** o
9a30: 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65  nly make a diffe
9a40: 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58  rence on Mac OSX
9a50: 20 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74   for the default
9a60: 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a   SQLite code..**
9a70: 20 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46   (Third-party VF
9a80: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
9a90: 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b  s might also mak
9aa0: 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f  e the distinctio
9ab0: 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c  n.** between SQL
9ac0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20  ITE_SYNC_NORMAL 
9ad0: 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  and SQLITE_SYNC_
9ae0: 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20  FULL, but among 
9af0: 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67  the.** operating
9b00: 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c   systems nativel
9b10: 79 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  y supported by S
9b20: 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20  QLite, only Mac 
9b30: 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f  OSX.** cares abo
9b40: 75 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63  ut the differenc
9b50: 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e.).*/.#define S
9b60: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
9b70: 4c 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32  L        0x00002
9b80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9b90: 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20  SYNC_FULL       
9ba0: 20 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69     0x00003.#defi
9bb0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  ne SQLITE_SYNC_D
9bc0: 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30  ATAONLY      0x0
9bd0: 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0010../*.** CAPI
9be0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
9bf0: 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e  ce Open File Han
9c00: 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71  dle.**.** An [sq
9c10: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9c20: 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  ct represents an
9c30: 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68   open file in th
9c40: 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  e .** [sqlite3_v
9c50: 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63  fs | OS interfac
9c60: 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76  e layer].  Indiv
9c70: 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61  idual OS interfa
9c80: 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  ce.** implementa
9c90: 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61  tions will.** wa
9ca0: 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74  nt to subclass t
9cb0: 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70  his object by ap
9cc0: 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e  pending addition
9cd0: 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72  al fields.** for
9ce0: 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20   their own use. 
9cf0: 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e   The pMethods en
9d00: 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72  try is a pointer
9d10: 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
9d20: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
9d30: 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
9d40: 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70  es methods for p
9d50: 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f  erforming.** I/O
9d60: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74   operations on t
9d70: 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f  he open file..*/
9d80: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
9d90: 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c  sqlite3_file sql
9da0: 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63  ite3_file;.struc
9db0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b  t sqlite3_file {
9dc0: 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20  .  const struct 
9dd0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
9de0: 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f  ds *pMethods;  /
9df0: 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e  * Methods for an
9e00: 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b   open file */.};
9e10: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
9e20: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46  : OS Interface F
9e30: 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68  ile Virtual Meth
9e40: 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ods Object.**.**
9e50: 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e   Every file open
9e60: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
9e70: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
9e80: 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61  thod populates a
9e90: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  n.** [sqlite3_fi
9ea0: 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20  le] object (or, 
9eb0: 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61  more commonly, a
9ec0: 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65   subclass of the
9ed0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9ee0: 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20  e] object) with 
9ef0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9f00: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
9f10: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73   object..** This
9f20: 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20   object defines 
9f30: 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64  the methods used
9f40: 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
9f50: 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ous operations.*
9f60: 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70  * against the op
9f70: 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e  en file represen
9f80: 74 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  ted by the [sqli
9f90: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
9fa0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ..**.** If the [
9fb0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
9fc0: 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74  n] method sets t
9fd0: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
9fe0: 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74  pMethods element
9ff0: 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55   .** to a non-NU
a000: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
a010: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f   the sqlite3_io_
a020: 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d  methods.xClose m
a030: 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20  ethod.** may be 
a040: 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20  invoked even if 
a050: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
a060: 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64  .xOpen] reported
a070: 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e   that it failed.
a080: 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61    The.** only wa
a090: 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63  y to prevent a c
a0a0: 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f  all to xClose fo
a0b0: 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64  llowing a failed
a0c0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
a0d0: 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74  pen].** is for t
a0e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
a0f0: 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68  xOpen] to set th
a100: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
a110: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a  Methods element.
a120: 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ** to NULL..**.*
a130: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
a140: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
a150: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
a160: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
a170: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
a180: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
a190: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
a1a0: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
a1b0: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
a1c0: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
a1d0: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
a1e0: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
a1f0: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
a200: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
a210: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
a220: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
a230: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
a240: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
a250: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
a260: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
a270: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
a280: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
a290: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
a2a0: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
a2b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
a2c0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
a2d0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
a2e0: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
a2f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
a300: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
a310: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
a320: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
a330: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
a340: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
a350: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
a360: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
a370: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
a380: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
a390: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
a3a0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
a3b0: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
a3c0: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
a3d0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
a3e0: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
a3f0: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
a400: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
a410: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
a420: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
a430: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
a440: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
a450: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
a460: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
a470: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
a480: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
a490: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
a4a0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
a4b0: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
a4c0: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
a4d0: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
a4e0: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
a4f0: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
a500: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
a510: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
a520: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
a530: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
a540: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
a550: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
a560: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
a570: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
a580: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
a590: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
a5a0: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
a5b0: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
a5c0: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
a5d0: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
a5e0: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
a5f0: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
a600: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
a610: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
a620: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
a630: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
a640: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
a650: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
a660: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
a670: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
a680: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
a690: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
a6a0: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
a6b0: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
a6c0: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
a6d0: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
a6e0: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
a6f0: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
a700: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
a710: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
a720: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
a730: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
a740: 73 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63  se..** A [file c
a750: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c  ontrol opcodes |
a760: 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73   list of opcodes
a770: 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  ] less than 100 
a780: 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a  is available..**
a790: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
a7a0: 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74  at define a cust
a7b0: 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  om xFileControl 
a7c0: 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73  method should us
a7d0: 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65  e opcodes.** gre
a7e0: 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f  ater than 100 to
a7f0: 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73   avoid conflicts
a800: 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  .  VFS implement
a810: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a  ations should.**
a820: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
a830: 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69  NOTFOUND] for fi
a840: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64  le control opcod
a850: 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  es that they do 
a860: 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65  not.** recognize
a870: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63  ..**.** The xSec
a880: 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64  torSize() method
a890: 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63   returns the sec
a8a0: 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a  tor size of the.
a8b0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75  ** device that u
a8c0: 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c  nderlies the fil
a8d0: 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73  e.  The sector s
a8e0: 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69  ize is the.** mi
a8f0: 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74  nimum write that
a900: 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65   can be performe
a910: 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72  d without distur
a920: 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79  bing.** other by
a930: 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e  tes in the file.
a940: 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61    The xDeviceCha
a950: 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a  racteristics().*
a960: 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
a970: 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65   a bit vector de
a980: 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f  scribing behavio
a990: 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64  rs of the.** und
a9a0: 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a  erlying device:.
a9b0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
a9c0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
a9d0: 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e  _ATOMIC].** <li>
a9e0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
a9f0: 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69  TOMIC512].** <li
aa00: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
aa10: 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC1K].** <li
aa20: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
aa30: 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC2K].** <li
aa40: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
aa50: 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC4K].** <li
aa60: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
aa70: 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69  ATOMIC8K].** <li
aa80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
aa90: 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC16K].** <l
aaa0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
aab0: 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c  _ATOMIC32K].** <
aac0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
aad0: 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20  P_ATOMIC64K].** 
aae0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
aaf0: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a  AP_SAFE_APPEND].
ab00: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
ab10: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
ab20: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
ab30: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
ab40: 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74  P_ATOMIC propert
ab50: 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c  y means that all
ab60: 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e   writes of.** an
ab70: 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69  y size are atomi
ab80: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
ab90: 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76  OCAP_ATOMICnnn v
aba0: 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68  alues.** mean th
abb0: 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f  at writes of blo
abc0: 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e  cks that are nnn
abd0: 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61   bytes in size a
abe0: 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65  nd.** are aligne
abf0: 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20  d to an address 
ac00: 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65  which is an inte
ac10: 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a  ger multiple of.
ac20: 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69  ** nnn are atomi
ac30: 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  c.  The SQLITE_I
ac40: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
ac50: 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20   value means.** 
ac60: 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69  that when data i
ac70: 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20  s appended to a 
ac80: 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69  file, the data i
ac90: 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69  s appended.** fi
aca0: 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a  rst then the siz
acb0: 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73  e of the file is
acc0: 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72   extended, never
acd0: 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61   the other.** wa
ace0: 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53  y around.  The S
acf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
ad00: 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20  ENTIAL property 
ad10: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e  means that.** in
ad20: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69  formation is wri
ad30: 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20  tten to disk in 
ad40: 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61  the same order a
ad50: 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57  s calls.** to xW
ad60: 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66  rite()..**.** If
ad70: 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73   xRead() returns
ad80: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
ad90: 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74  ORT_READ it must
ada0: 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e   also fill.** in
adb0: 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74   the unread port
adc0: 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66  ions of the buff
add0: 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20  er with zeros.  
ade0: 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61  A VFS that.** fa
adf0: 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ils to zero-fill
ae00: 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67   short reads mig
ae10: 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e  ht seem to work.
ae20: 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61    However,.** fa
ae30: 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69  ilure to zero-fi
ae40: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77  ll short reads w
ae50: 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c  ill eventually l
ae60: 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61  ead to.** databa
ae70: 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  se corruption..*
ae80: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
ae90: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
aea0: 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  ods sqlite3_io_m
aeb0: 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
aec0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
aed0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
aee0: 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f  on;.  int (*xClo
aef0: 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  se)(sqlite3_file
af00: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61  *);.  int (*xRea
af10: 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  d)(sqlite3_file*
af20: 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  , void*, int iAm
af30: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
af40: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
af50: 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33  *xWrite)(sqlite3
af60: 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f  _file*, const vo
af70: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
af80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
af90: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72  st);.  int (*xTr
afa0: 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f  uncate)(sqlite3_
afb0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
afc0: 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e  nt64 size);.  in
afd0: 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74  t (*xSync)(sqlit
afe0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c  e3_file*, int fl
aff0: 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  ags);.  int (*xF
b000: 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33  ileSize)(sqlite3
b010: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
b020: 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20  int64 *pSize);. 
b030: 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71   int (*xLock)(sq
b040: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
b050: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f  );.  int (*xUnlo
b060: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
b070: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
b080: 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c  *xCheckReservedL
b090: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
b0a0: 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74  e*, int *pResOut
b0b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
b0c0: 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33  Control)(sqlite3
b0d0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20  _file*, int op, 
b0e0: 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69  void *pArg);.  i
b0f0: 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65  nt (*xSectorSize
b100: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
b110: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63  ;.  int (*xDevic
b120: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
b130: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
b140: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
b150: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
b160: 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a  or version 1 */.
b170: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29    int (*xShmMap)
b180: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
b190: 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73  int iPg, int pgs
b1a0: 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c  z, int, void vol
b1b0: 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20  atile**);.  int 
b1c0: 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69  (*xShmLock)(sqli
b1d0: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f  te3_file*, int o
b1e0: 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e  ffset, int n, in
b1f0: 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64  t flags);.  void
b200: 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28   (*xShmBarrier)(
b210: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
b220: 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61    int (*xShmUnma
b230: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
b240: 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67  , int deleteFlag
b250: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
b260: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
b270: 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f  for version 2 */
b280: 0a 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29  .  int (*xFetch)
b290: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
b2a0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
b2b0: 66 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76  fst, int iAmt, v
b2c0: 6f 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74  oid **pp);.  int
b2d0: 20 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c   (*xUnfetch)(sql
b2e0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
b2f0: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c  te3_int64 iOfst,
b300: 20 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20   void *p);.  /* 
b310: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
b320: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
b330: 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 3 */.  /* Ad
b340: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
b350: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
b360: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
b370: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
b380: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
b390: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
b3a0: 63 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  codes.** KEYWORD
b3b0: 53 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  S: {file control
b3c0: 20 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20   opcodes} {file 
b3d0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a  control opcode}.
b3e0: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
b3f0: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
b400: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
b410: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
b420: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
b430: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
b440: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
b450: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
b460: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
b470: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
b480: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
b490: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b4a0: 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54  LOCKSTATE]].** T
b4b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b4c0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
b4d0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
b4e0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
b4f0: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
b500: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
b510: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
b520: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
b530: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
b540: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
b550: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
b560: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
b570: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
b580: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
b590: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
b5a0: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
b5b0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
b5c0: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
b5d0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
b5e0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
b5f0: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
b600: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
b610: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
b620: 67 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76  g and is only av
b630: 61 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65  ailable when the
b640: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
b650: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b660: 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
b670: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
b680: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
b690: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b6a0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
b6b0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
b6c0: 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69   by SQLite to gi
b6d0: 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61  ve the VFS.** la
b6e0: 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f  yer a hint of ho
b6f0: 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61  w large the data
b700: 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67  base file will g
b710: 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67  row to be during
b720: 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20   the.** current 
b730: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68  transaction.  Th
b740: 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67  is hint is not g
b750: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
b760: 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a  accurate but it.
b770: 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73  ** is often clos
b780: 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69  e.  The underlyi
b790: 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f  ng VFS might cho
b7a0: 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61  ose to prealloca
b7b0: 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  te database.** f
b7c0: 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20  ile space based 
b7d0: 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20  on this hint in 
b7e0: 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72  order to help wr
b7f0: 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61  ites to the data
b800: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e  base.** file run
b810: 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c   faster..**.** <
b820: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b830: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a  L_CHUNK_SIZE]].*
b840: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b850: 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20  NTL_CHUNK_SIZE] 
b860: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
b870: 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74  o request that t
b880: 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64  he VFS.** extend
b890: 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20  s and truncates 
b8a0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
b8b0: 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61  e in chunks of a
b8c0: 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a   size specified.
b8d0: 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20  ** by the user. 
b8e0: 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
b8f0: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
b900: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
b910: 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74  should .** point
b920: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28   to an integer (
b930: 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69  type int) contai
b940: 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75  ning the new chu
b950: 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a  nk-size to use.*
b960: 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61  * for the nomina
b970: 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c  ted database. Al
b980: 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73  locating databas
b990: 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20  e file space in 
b9a0: 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20  large.** chunks 
b9b0: 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69  (say 1MB at a ti
b9c0: 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20  me), may reduce 
b9d0: 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67  file-system frag
b9e0: 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  mentation and.**
b9f0: 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d   improve perform
ba00: 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73  ance on some sys
ba10: 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tems..**.** <li>
ba20: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  [[SQLITE_FCNTL_F
ba30: 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  ILE_POINTER]].**
ba40: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
ba50: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
ba60: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
ba70: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e  to obtain a poin
ba80: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
ba90: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
baa0: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  ect associated w
bab0: 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
bac0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
bad0: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c  nection.  See al
bae0: 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  so [SQLITE_FCNTL
baf0: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
bb00: 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  ]..**.** <li>[[S
bb10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
bb20: 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a  NAL_POINTER]].**
bb30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
bb40: 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54  TL_JOURNAL_POINT
bb50: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ER] opcode is us
bb60: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70  ed to obtain a p
bb70: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
bb80: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
bb90: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65  object associate
bba0: 64 20 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e  d with the journ
bbb0: 61 6c 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a  al file (either.
bbc0: 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b  ** the [rollback
bbd0: 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65   journal] or the
bbe0: 20 5b 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f   [write-ahead lo
bbf0: 67 5d 29 20 66 6f 72 20 61 20 70 61 72 74 69 63  g]) for a partic
bc00: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
bc10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
bc20: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46  e also [SQLITE_F
bc30: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
bc40: 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  R]..**.** <li>[[
bc50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
bc60: 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e  C_OMITTED]].** N
bc70: 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e  o longer in use.
bc80: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bc90: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d  ITE_FCNTL_SYNC]]
bca0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
bcb0: 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f  FCNTL_SYNC] opco
bcc0: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
bcd0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51  internally by SQ
bce0: 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74  Lite and.** sent
bcf0: 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65   to the VFS imme
bd00: 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74  diately before t
bd10: 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20  he xSync method 
bd20: 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a  is invoked on a.
bd30: 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ** database file
bd40: 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c   descriptor. Or,
bd50: 20 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65   if the xSync me
bd60: 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f  thod is not invo
bd70: 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20  ked .** because 
bd80: 74 68 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e  the user has con
bd90: 66 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 77  figured SQLite w
bda0: 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20  ith .** [PRAGMA 
bdb0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52  synchronous | PR
bdc0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
bdd0: 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f  =OFF] it is invo
bde0: 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a  ked in place .**
bdf0: 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65   of the xSync me
be00: 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61  thod. In most ca
be10: 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72  ses, the pointer
be20: 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
be30: 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69   with.** this fi
be40: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55  le-control is NU
be50: 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20  LL. However, if 
be60: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
be70: 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65  e is being synce
be80: 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  d.** as part of 
be90: 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65  a multi-database
bea0: 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67   commit, the arg
beb0: 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20  ument points to 
bec0: 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
bed0: 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
bee0: 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61  ining the transa
bef0: 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f  ctions master-jo
bf00: 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e  urnal file name.
bf10: 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20   VFSes that .** 
bf20: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
bf30: 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73   signal should s
bf40: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
bf50: 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c  his opcode. Appl
bf60: 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f  ications .** sho
bf70: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71  uld not call [sq
bf80: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
bf90: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 20  ol()] with this 
bfa0: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
bfb0: 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75  so may .** disru
bfc0: 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  pt the operation
bfd0: 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69   of the speciali
bfe0: 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20 64  zed VFSes that d
bff0: 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a  o require it.  .
c000: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c010: 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f  TE_FCNTL_COMMIT_
c020: 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68  PHASETWO]].** Th
c030: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c040: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d  COMMIT_PHASETWO]
c050: 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72   opcode is gener
c060: 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ated internally 
c070: 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
c080: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53   sent to the VFS
c090: 20 61 66 74 65 72 20 61 20 74 72 61 6e 73 61 63   after a transac
c0a0: 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f  tion has been co
c0b0: 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74  mmitted immediat
c0c0: 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72  ely.** but befor
c0d0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  e the database i
c0e0: 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65  s unlocked. VFSe
c0f0: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65  s that do not ne
c100: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a  ed this signal.*
c110: 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  * should silentl
c120: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
c130: 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f  code. Applicatio
c140: 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61  ns should not ca
c150: 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ll.** [sqlite3_f
c160: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
c170: 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20  ith this opcode 
c180: 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20  as doing so may 
c190: 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20  disrupt the .** 
c1a0: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
c1b0: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
c1c0: 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  es that do requi
c1d0: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
c1e0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
c1f0: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
c200: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
c210: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
c220: 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20  V_RETRY] opcode 
c230: 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
c240: 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a  gure automatic.*
c250: 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61  * retry counts a
c260: 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72  nd intervals for
c270: 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f   certain disk I/
c280: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72  O operations for
c290: 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20   the.** windows 
c2a0: 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74  [VFS] in order t
c2b0: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
c2c0: 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73  ness in the pres
c2d0: 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d  ence of.** anti-
c2e0: 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20  virus programs. 
c2f0: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
c300: 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c   windows VFS wil
c310: 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61  l retry file rea
c320: 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65  d,.** file write
c330: 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74  , and file delet
c340: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20  e operations up 
c350: 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74  to 10 times, wit
c360: 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20  h a delay.** of 
c370: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
c380: 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74  before the first
c390: 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20   retry and with 
c3a0: 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61  the delay increa
c3b0: 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64  sing.** by an ad
c3c0: 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c  ditional 25 mill
c3d0: 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61  iseconds with ea
c3e0: 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65  ch subsequent re
c3f0: 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  try.  This.** op
c400: 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73  code allows thes
c410: 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30  e two values (10
c420: 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20   retries and 25 
c430: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
c440: 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20  delay).** to be 
c450: 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76  adjusted.  The v
c460: 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65  alues are change
c470: 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61  d for all databa
c480: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
c490: 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  * within the sam
c4a0: 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20  e process.  The 
c4b0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
c4c0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61  inter to an arra
c4d0: 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65  y of two.** inte
c4e0: 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66  gers where the f
c4f0: 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74  irst integer i t
c500: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75  he new retry cou
c510: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nt and the secon
c520: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20  d.** integer is 
c530: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65  the delay.  If e
c540: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73  ither integer is
c550: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
c560: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69  the setting.** i
c570: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75  s not changed bu
c580: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72  t instead the pr
c590: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61  ior value of tha
c5a0: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69  t setting is wri
c5b0: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  tten.** into the
c5c0: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c   array entry, al
c5d0: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65  lowing the curre
c5e0: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67  nt retry setting
c5f0: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72  s to be.** inter
c600: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44  rogated.  The zD
c610: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  bName parameter 
c620: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
c630: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
c640: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
c650: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
c660: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
c670: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
c680: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
c690: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
c6a0: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
c6b0: 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73  ite Ahead Log] s
c6c0: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
c6d0: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
c6e0: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
c6f0: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
c700: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
c710: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
c720: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
c730: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
c740: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
c750: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
c760: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
c770: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
c780: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
c790: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
c7a0: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
c7b0: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
c7c0: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
c7d0: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
c7e0: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
c7f0: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
c800: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
c810: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
c820: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
c830: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
c840: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
c850: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
c860: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
c870: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
c880: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
c890: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
c8a0: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
c8b0: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
c8c0: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
c8d0: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
c8e0: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
c8f0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
c900: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
c910: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
c920: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
c930: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
c940: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
c950: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
c960: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
c970: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
c980: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
c990: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
c9a0: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
c9b0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
c9c0: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
c9d0: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
c9e0: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
c9f0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ca00: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
ca10: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
ca20: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ca30: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
ca40: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
ca50: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
ca60: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
ca70: 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61  sistent "powersa
ca80: 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72  fe-overwrite" or
ca90: 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e   "PSOW" setting.
caa0: 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69    The PSOW setti
cab0: 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73  ng.** determines
cac0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43   the [SQLITE_IOC
cad0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
cae0: 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74  RWRITE] bit of t
caf0: 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61  he.** xDeviceCha
cb00: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
cb10: 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68  hods. The fourth
cb20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
cb30: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
cb40: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
cb50: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
cb60: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
cb70: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
cb80: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
cb90: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72  0 to disable zer
cba0: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72  o-damage mode or
cbb0: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72   1 to enable zer
cbc0: 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65  o-damage.** mode
cbd0: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
cbe0: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
cbf0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
cc00: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
cc10: 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  .** zero-damage 
cc20: 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  mode setting..**
cc30: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
cc40: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
cc50: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
cc60: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
cc70: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e  TE] opcode is in
cc80: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
cc90: 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a  after opening.**
cca0: 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63   a write transac
ccb0: 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  tion to indicate
ccc0: 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74   that, unless it
ccd0: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   is rolled back 
cce0: 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73  for some.** reas
ccf0: 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64  on, the entire d
cd00: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
cd10: 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  l be overwritten
cd20: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
cd30: 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  .** transaction.
cd40: 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79   This is used by
cd50: 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f   VACUUM operatio
cd60: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ns..**.** <li>[[
cd70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
cd80: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NAME]].** ^The [
cd90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
cda0: 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NAME] opcode can
cdb0: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
cdc0: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a  in the names of.
cdd0: 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69  ** all [VFSes] i
cde0: 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e  n the VFS stack.
cdf0: 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20    The names are 
ce00: 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73  of all VFS shims
ce10: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61   and the.** fina
ce20: 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56  l bottom-level V
ce30: 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69  FS are written i
ce40: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
ce50: 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
ce60: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
ce70: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69  and the result i
ce80: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  s stored in the 
ce90: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a  char* variable.*
cea0: 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74  * that the fourt
ceb0: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b  h parameter of [
cec0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
ced0: 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74  trol()] points t
cee0: 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72  o..** The caller
cef0: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
cf00: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20  for freeing the 
cf10: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65  memory when done
cf20: 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c  .  As with.** al
cf30: 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61  l file-control a
cf40: 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73  ctions, there is
cf50: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68   no guarantee th
cf60: 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74  at this will act
cf70: 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74  ually.** do anyt
cf80: 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73  hing.  Callers s
cf90: 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65  hould initialize
cfa0: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
cfb0: 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a  ble to a NULL.**
cfc0: 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65   pointer in case
cfd0: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
cfe0: 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  ol is not implem
cff0: 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c  ented.  This fil
d000: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20  e-control.** is 
d010: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61  intended for dia
d020: 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79  gnostic use only
d030: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
d040: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50  LITE_FCNTL_VFS_P
d050: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65  OINTER]].** ^The
d060: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
d070: 46 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  FS_POINTER] opco
d080: 64 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74  de finds a point
d090: 65 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65  er to the top-le
d0a0: 76 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63  vel.** [VFSes] c
d0b0: 75 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e  urrently in use.
d0c0: 20 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74    ^(The argument
d0d0: 20 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   X in.** sqlite3
d0e0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62  _file_control(db
d0f0: 2c 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  ,SQLITE_FCNTL_VF
d100: 53 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73  S_POINTER,X) mus
d110: 74 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20  t be.** of type 
d120: 22 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a  "[sqlite3_vfs] *
d130: 2a 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65  *".  This opcode
d140: 73 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a  s will set *X.**
d150: 20 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   to a pointer to
d160: 20 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56   the top-level V
d170: 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74  FS.)^.** ^When t
d180: 68 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c  here are multipl
d190: 65 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74  e VFS shims in t
d1a0: 68 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f  he stack, this o
d1b0: 70 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a  pcode finds the.
d1c0: 2a 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68  ** upper-most sh
d1d0: 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c  im only..**.** <
d1e0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
d1f0: 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57  L_PRAGMA]].** ^W
d200: 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d  henever a [PRAGM
d210: 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  A] statement is 
d220: 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49  parsed, an [SQLI
d230: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
d240: 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f   .** file contro
d250: 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65  l is sent to the
d260: 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   open [sqlite3_f
d270: 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72  ile] object corr
d280: 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20  esponding.** to 
d290: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
d2a0: 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70  e to which the p
d2b0: 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20  ragma statement 
d2c0: 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67  refers. ^The arg
d2d0: 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20  ument.** to the 
d2e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
d2f0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
d300: 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ol is an array o
d310: 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  f.** pointers to
d320: 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a   strings (char**
d330: 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73  ) in which the s
d340: 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66  econd element of
d350: 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73   the array.** is
d360: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
d370: 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20   pragma and the 
d380: 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73  third element is
d390: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
d3a0: 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f   the.** pragma o
d3b0: 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72  r NULL if the pr
d3c0: 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75  agma has no argu
d3d0: 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64  ment.  ^The hand
d3e0: 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53  ler for an.** [S
d3f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
d400: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
d410: 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20   can optionally 
d420: 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65  make the first e
d430: 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65  lement.** of the
d440: 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74   char** argument
d450: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69   point to a stri
d460: 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ng obtained from
d470: 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   [sqlite3_mprint
d480: 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65  f()].** or the e
d490: 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68  quivalent and th
d4a0: 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  at string will b
d4b0: 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74  ecome the result
d4c0: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f   of the pragma o
d4d0: 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d  r.** the error m
d4e0: 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72  essage if the pr
d4f0: 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20  agma fails. ^If 
d500: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  the.** [SQLITE_F
d510: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
d520: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
d530: 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  s [SQLITE_NOTFOU
d540: 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c  ND], then normal
d550: 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72   .** [PRAGMA] pr
d560: 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75  ocessing continu
d570: 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  es.  ^If the [SQ
d580: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
d590: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
d5a0: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
d5b0: 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65  TE_OK], then the
d5c0: 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20   parser assumes 
d5d0: 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20  that the.** VFS 
d5e0: 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20  has handled the 
d5f0: 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e  PRAGMA itself an
d600: 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e  d the parser gen
d610: 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a  erates a no-op.*
d620: 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
d630: 6d 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73  ment if result s
d640: 74 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f  tring is NULL, o
d650: 72 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61  r that returns a
d660: 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20   copy.** of the 
d670: 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66  result string if
d680: 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e   the string is n
d690: 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20  on-NULL..** ^If 
d6a0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
d6b0: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
d6c0: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a  ontrol returns.*
d6d0: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64  * any result cod
d6e0: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
d6f0: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c  LITE_OK] or [SQL
d700: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
d710: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  hat means.** tha
d720: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e  t the VFS encoun
d730: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77  tered an error w
d740: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68  hile handling th
d750: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74  e [PRAGMA] and t
d760: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f  he.** compilatio
d770: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20  n of the PRAGMA 
d780: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
d790: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ror.  ^The [SQLI
d7a0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
d7b0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
d7c0: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62   occurs at the b
d7d0: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67  eginning of prag
d7e0: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61  ma statement ana
d7f0: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20  lysis and so.** 
d800: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76  it is able to ov
d810: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20  erride built-in 
d820: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
d830: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nts..**.** <li>[
d840: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
d850: 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e  SYHANDLER]].** ^
d860: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d870: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a  L_BUSYHANDLER].*
d880: 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d  * file-control m
d890: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79  ay be invoked by
d8a0: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64   SQLite on the d
d8b0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e  atabase file han
d8c0: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61  dle.** shortly a
d8d0: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65  fter it is opene
d8e0: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  d in order to pr
d8f0: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56  ovide a custom V
d900: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a  FS with access.*
d910: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74  * to the connect
d920: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65  ions busy-handle
d930: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20  r callback. The 
d940: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74  argument is of t
d950: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a  ype (void **).**
d960: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74   - an array of t
d970: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75  wo (void *) valu
d980: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76  es. The first (v
d990: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20  oid *) actually 
d9a0: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66  points.** to a f
d9b0: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
d9c0: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29  (int (*)(void *)
d9d0: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69  ). In order to i
d9e0: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63  nvoke the connec
d9f0: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61  tions.** busy-ha
da00: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63  ndler, this func
da10: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69  tion should be i
da20: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20  nvoked with the 
da30: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20  second (void *) 
da40: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20  in.** the array 
da50: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75  as the only argu
da60: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75  ment. If it retu
da70: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
da80: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  en the operation
da90: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
daa0: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74  tried. If it ret
dab0: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63  urns zero, the c
dac0: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64  ustom VFS should
dad0: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20   abandon the.** 
dae0: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
daf0: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
db00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
db10: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41  FILENAME]].** ^A
db20: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69  pplication can i
db30: 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54  nvoke the [SQLIT
db40: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
db50: 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72  NAME] file-contr
db60: 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51  ol.** to have SQ
db70: 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a  Lite generate a.
db80: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
db90: 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ename using the 
dba0: 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74  same algorithm t
dbb0: 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20  hat is followed 
dbc0: 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74  to generate.** t
dbd0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
dbe0: 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c  es for TEMP tabl
dbf0: 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74  es and other int
dc00: 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65  ernal uses.  The
dc10: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
dc20: 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20  uld be a char** 
dc30: 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69  which will be fi
dc40: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69  lled with the fi
dc50: 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65  lename.** writte
dc60: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
dc70: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
dc80: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
dc90: 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75   The caller shou
dca0: 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71  ld.** invoke [sq
dcb0: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
dcc0: 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61   the result to a
dcd0: 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65  void a memory le
dce0: 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ak..**.** <li>[[
dcf0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
dd00: 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  P_SIZE]].** The 
dd10: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d  [SQLITE_FCNTL_MM
dd20: 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f  AP_SIZE] file co
dd30: 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f  ntrol is used to
dd40: 20 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68   query or set th
dd50: 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  e.** maximum num
dd60: 62 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61  ber of bytes tha
dd70: 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66  t will be used f
dd80: 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64  or memory-mapped
dd90: 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67   I/O..** The arg
dda0: 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
ddb0: 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66  er to a value of
ddc0: 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e   type sqlite3_in
ddd0: 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61  t64 that.** is a
dde0: 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d  n advisory maxim
ddf0: 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  um number of byt
de00: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74  es in the file t
de10: 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54  o memory map.  T
de20: 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73  he.** pointer is
de30: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74   overwritten wit
de40: 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e  h the old value.
de50: 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e    The limit is n
de60: 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a  ot changed if.**
de70: 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69   the value origi
de80: 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f  nally pointed to
de90: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e   is negative, an
dea0: 64 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74  d so the current
deb0: 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62   limit .** can b
dec0: 65 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73  e queried by pas
ded0: 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65  sing in a pointe
dee0: 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20  r to a negative 
def0: 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a  number.  This.**
df00: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
df10: 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
df20: 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50   to implement [P
df30: 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d  RAGMA mmap_size]
df40: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
df50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
df60: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
df70: 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66  E_FCNTL_TRACE] f
df80: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76  ile control prov
df90: 69 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e  ides advisory in
dfa0: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  formation.** to 
dfb0: 74 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68  the VFS about wh
dfc0: 61 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61  at the higher la
dfd0: 79 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69  yers of the SQLi
dfe0: 74 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69  te stack are doi
dff0: 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65  ng..** This file
e000: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64   control is used
e010: 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74   by some VFS act
e020: 69 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73  ivity tracing [s
e030: 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72  hims]..** The ar
e040: 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f  gument is a zero
e050: 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
e060: 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65  ng.  Higher laye
e070: 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c  rs in the.** SQL
e080: 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65  ite stack may ge
e090: 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73  nerate instances
e0a0: 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f   of this file co
e0b0: 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20  ntrol if.** the 
e0c0: 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54  [SQLITE_USE_FCNT
e0d0: 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65  L_TRACE] compile
e0e0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
e0f0: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  enabled..**.** <
e100: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
e110: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a  L_HAS_MOVED]].**
e120: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
e130: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69  TL_HAS_MOVED] fi
e140: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72  le control inter
e150: 70 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65  prets its argume
e160: 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  nt as a.** point
e170: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
e180: 20 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61   and it writes a
e190: 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68   boolean into th
e1a0: 61 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e  at integer depen
e1b0: 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68  ding.** on wheth
e1c0: 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69  er or not the fi
e1d0: 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61  le has been rena
e1e0: 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64  med, moved, or d
e1f0: 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a  eleted since it.
e200: 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65  ** was first ope
e210: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ned..**.** <li>[
e220: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
e230: 4e 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d  N32_GET_HANDLE]]
e240: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
e250: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
e260: 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63  HANDLE] opcode c
e270: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
e280: 74 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65  tain the.** unde
e290: 72 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69  rlying native fi
e2a0: 6c 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69  le handle associ
e2b0: 61 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65  ated with a file
e2c0: 20 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66   handle.  This f
e2d0: 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69  ile.** control i
e2e0: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72  nterprets its ar
e2f0: 67 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e  gument as a poin
e300: 74 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20  ter to a native 
e310: 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a  file handle and.
e320: 2a 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65  ** writes the re
e330: 73 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68  sulting value th
e340: 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ere..**.** <li>[
e350: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
e360: 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d  N32_SET_HANDLE]]
e370: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
e380: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
e390: 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69  HANDLE] opcode i
e3a0: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
e3b0: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
e3c0: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
e3d0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
e3e0: 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65  thod to swap the
e3f0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74   file handle wit
e400: 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69  h the one.** poi
e410: 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70  nted to by the p
e420: 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Arg argument.  T
e430: 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69  his capability i
e440: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
e450: 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c  sting.** and onl
e460: 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75  y needs to be su
e470: 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c  pported when SQL
e480: 49 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69  ITE_TEST is defi
e490: 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ned..**.** <li>[
e4a0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
e4b0: 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65  L_BLOCK]].** The
e4c0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
e4d0: 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73  AL_BLOCK] is a s
e4e0: 69 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53  ignal to the VFS
e4f0: 20 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d   layer that it m
e500: 69 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e  ight.** be advan
e510: 74 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b  tageous to block
e520: 20 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c   on the next WAL
e530: 20 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63   lock if the loc
e540: 6b 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61  k is not immedia
e550: 74 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c  tely.** availabl
e560: 65 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73  e.  The WAL subs
e570: 79 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69  ystem issues thi
e580: 73 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20  s signal during 
e590: 72 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74  rare.** circumst
e5a0: 61 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74  ances in order t
e5b0: 6f 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20  o fix a problem 
e5c0: 77 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e  with priority in
e5d0: 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c  version..** Appl
e5e0: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
e5f0: 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65  <em>not</em> use
e600: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
e610: 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ol..**.** <li>[[
e620: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50  SQLITE_FCNTL_ZIP
e630: 56 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  VFS]].** The [SQ
e640: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46  LITE_FCNTL_ZIPVF
e650: 53 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70  S] opcode is imp
e660: 6c 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76  lemented by zipv
e670: 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68  fs only. All oth
e680: 65 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64  er.** VFS should
e690: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e   return SQLITE_N
e6a0: 4f 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73  OTFOUND for this
e6b0: 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c   opcode..**.** <
e6c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
e6d0: 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b  L_RBU]].** The [
e6e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55  SQLITE_FCNTL_RBU
e6f0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
e700: 65 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73  emented by the s
e710: 70 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20  pecial VFS used 
e720: 62 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78  by.** the RBU ex
e730: 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41  tension only.  A
e740: 6c 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f  ll other VFS sho
e750: 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54  uld return SQLIT
e760: 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a  E_NOTFOUND for.*
e770: 2a 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20  * this opcode.  
e780: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65  .** </ul>.*/.#de
e790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
e7a0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20  L_LOCKSTATE     
e7b0: 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
e7c0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
e7d0: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
e7e0: 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69  LE       2.#defi
e7f0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
e800: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
e810: 45 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  E       3.#defin
e820: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
e830: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
e840: 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
e850: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49   SQLITE_FCNTL_SI
e860: 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20  ZE_HINT         
e870: 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
e880: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
e890: 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20  NK_SIZE         
e8a0: 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
e8b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
e8c0: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
e8d0: 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
e8e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
e8f0: 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20  OMITTED         
e900: 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
e910: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
e920: 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20  AV_RETRY        
e930: 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
e940: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
e950: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
e960: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
e970: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
e980: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31  E              1
e990: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
e9a0: 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20  _FCNTL_VFSNAME  
e9b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32                12
e9c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e9d0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
e9e0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a  OVERWRITE    13.
e9f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ea00: 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20  CNTL_PRAGMA     
ea10: 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23              14.#
ea20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ea30: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20  NTL_BUSYHANDLER 
ea40: 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64             15.#d
ea50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ea60: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20  TL_TEMPFILENAME 
ea70: 20 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65            16.#de
ea80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ea90: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20  L_MMAP_SIZE     
eaa0: 20 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66           18.#def
eab0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
eac0: 5f 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20  _TRACE          
ead0: 20 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69          19.#defi
eae0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
eaf0: 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20  HAS_MOVED       
eb00: 20 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e         20.#defin
eb10: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
eb20: 59 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20  YNC             
eb30: 20 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65        21.#define
eb40: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f   SQLITE_FCNTL_CO
eb50: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20  MMIT_PHASETWO   
eb60: 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20       22.#define 
eb70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
eb80: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20  32_SET_HANDLE   
eb90: 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53      23.#define S
eba0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f  QLITE_FCNTL_WAL_
ebb0: 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  BLOCK           
ebc0: 20 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51     24.#define SQ
ebd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46  LITE_FCNTL_ZIPVF
ebe0: 53 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  S               
ebf0: 20 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c    25.#define SQL
ec00: 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20  ITE_FCNTL_RBU   
ec10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
ec20: 20 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   26.#define SQLI
ec30: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49  TE_FCNTL_VFS_POI
ec40: 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20  NTER            
ec50: 32 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  27.#define SQLIT
ec60: 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f  E_FCNTL_JOURNAL_
ec70: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32  POINTER        2
ec80: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
ec90: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54  _FCNTL_WIN32_GET
eca0: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39  _HANDLE       29
ecb0: 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20  ../* deprecated 
ecc0: 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  names */.#define
ecd0: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
ece0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53  PROXYFILE      S
ecf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f  QLITE_FCNTL_GET_
ed00: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64  LOCKPROXYFILE.#d
ed10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54  efine SQLITE_SET
ed20: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
ed30: 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c      SQLITE_FCNTL
ed40: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
ed50: 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  LE.#define SQLIT
ed60: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
ed70: 20 20 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f           SQLITE_
ed80: 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f  FCNTL_LAST_ERRNO
ed90: 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
eda0: 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a  F: Mutex Handle.
edb0: 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20  **.** The mutex 
edc0: 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51  module within SQ
edd0: 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71  Lite defines [sq
ede0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20  lite3_mutex] to 
edf0: 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63  be an.** abstrac
ee00: 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74  t type for a mut
ee10: 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  ex object.  The 
ee20: 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65  SQLite core neve
ee30: 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68  r looks.** at th
ee40: 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
ee50: 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  sentation of an 
ee60: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e  [sqlite3_mutex].
ee70: 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61    It only.** dea
ee80: 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73  ls with pointers
ee90: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
eea0: 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a  _mutex] object..
eeb0: 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72  **.** Mutexes ar
eec0: 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20  e created using 
eed0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61  [sqlite3_mutex_a
eee0: 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  lloc()]..*/.type
eef0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
ef00: 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33  e3_mutex sqlite3
ef10: 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _mutex;../*.** C
ef20: 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c  API3REF: Loadabl
ef30: 65 20 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e  e Extension Thun
ef40: 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  k.**.** A pointe
ef50: 72 20 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20  r to the opaque 
ef60: 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74  sqlite3_api_rout
ef70: 69 6e 65 73 20 73 74 72 75 63 74 75 72 65 20 69  ines structure i
ef80: 73 20 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74  s passed as.** t
ef90: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
efa0: 65 72 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e  er to entry poin
efb0: 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20  ts of [loadable 
efc0: 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68  extensions].  Th
efd0: 69 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  is.** structure 
efe0: 6d 75 73 74 20 62 65 20 74 79 70 65 64 65 66 65  must be typedefe
eff0: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f  d in order to wo
f000: 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c  rk around compil
f010: 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f  er warnings.** o
f020: 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73  n some platforms
f030: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
f040: 75 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f  uct sqlite3_api_
f050: 72 6f 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33  routines sqlite3
f060: 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a  _api_routines;..
f070: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f080: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
f090: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
f0a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
f0b0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
f0c0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
f0d0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
f0e0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
f0f0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
f100: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
f110: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
f120: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
f130: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
f140: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
f150: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
f160: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
f170: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
f180: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
f190: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
f1a0: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
f1b0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
f1c0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
f1d0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
f1e0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
f1f0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
f200: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
f210: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
f220: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
f230: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
f240: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
f250: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
f260: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
f270: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
f280: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
f290: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
f2a0: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
f2b0: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
f2c0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
f2d0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
f2e0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
f2f0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
f300: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
f310: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
f320: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
f330: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
f340: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
f350: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
f360: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
f370: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
f380: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
f390: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
f3a0: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
f3b0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
f3c0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
f3d0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
f3e0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
f3f0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
f400: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
f410: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
f420: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
f430: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
f440: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
f450: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
f460: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
f470: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
f480: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
f490: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
f4a0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
f4b0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
f4c0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
f4d0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
f4e0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
f4f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
f500: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
f510: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
f520: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
f530: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
f540: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
f550: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
f560: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
f570: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
f580: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
f590: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
f5a0: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
f5b0: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
f5c0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
f5d0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
f5e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
f5f0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
f600: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
f610: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
f620: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
f630: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
f640: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
f650: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
f660: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
f670: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
f680: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
f690: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
f6a0: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
f6b0: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
f6c0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
f6d0: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
f6e0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
f6f0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
f700: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
f710: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
f720: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
f730: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
f740: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
f750: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
f760: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
f770: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
f780: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
f790: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
f7a0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
f7b0: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
f7c0: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
f7d0: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
f7e0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
f7f0: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
f800: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
f810: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
f820: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
f830: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
f840: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
f850: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
f860: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
f870: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
f880: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
f890: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
f8a0: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
f8b0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
f8c0: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
f8d0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
f8e0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
f8f0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
f900: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
f910: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
f920: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
f930: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
f940: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
f950: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
f960: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
f970: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
f980: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
f990: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
f9a0: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
f9b0: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
f9c0: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
f9d0: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
f9e0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
f9f0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
fa00: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
fa10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
fa20: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
fa30: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
fa40: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
fa50: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
fa60: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
fa70: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
fa80: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
fa90: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
faa0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
fab0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
fac0: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
fad0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
fae0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
faf0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
fb00: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
fb10: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
fb20: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
fb30: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
fb40: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
fb50: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
fb60: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
fb70: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
fb80: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
fb90: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
fba0: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
fbb0: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
fbc0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
fbd0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
fbe0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
fbf0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
fc00: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
fc10: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
fc20: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
fc30: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
fc40: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
fc50: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
fc60: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
fc70: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
fc80: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
fc90: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
fca0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
fcb0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
fcc0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
fcd0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
fce0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
fcf0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
fd00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
fd10: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
fd20: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
fd30: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
fd40: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
fd50: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
fd60: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
fd70: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
fd80: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
fd90: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
fda0: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
fdb0: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
fdc0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
fdd0: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
fde0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
fdf0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
fe00: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
fe10: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
fe20: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
fe30: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
fe40: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
fe50: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
fe60: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
fe70: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
fe80: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
fe90: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
fea0: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
feb0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
fec0: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
fed0: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
fee0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
fef0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
ff00: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
ff10: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
ff20: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
ff30: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
ff40: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
ff50: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
ff60: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
ff70: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
ff80: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
ff90: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
ffa0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
ffb0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
ffc0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
ffd0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
ffe0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
fff0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
10000 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
10010 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
10020 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
10030 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
10040 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
10050 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
10060 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
10070 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
10080 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
10090 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
100a0 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
100b0 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
100c0 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
100d0 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
100e0 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
100f0 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
10100 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
10110 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
10120 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
10130 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
10140 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
10150 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
10160 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
10170 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
10180 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
10190 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
101a0 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
101b0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
101c0 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
101d0 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
101e0 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
101f0 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
10200 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
10210 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
10220 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
10230 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
10240 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
10250 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
10260 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
10270 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
10280 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
10290 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
102a0 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
102b0 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
102c0 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
102d0 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
102e0 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
102f0 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
10300 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
10310 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
10320 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
10330 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
10340 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
10350 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
10360 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
10370 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
10380 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
10390 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
103a0 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
103b0 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
103c0 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
103d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
103e0 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
103f0 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
10400 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
10410 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
10420 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
10430 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
10440 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
10450 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
10460 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
10470 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
10480 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
10490 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
104a0 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
104b0 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
104c0 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
104d0 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
104e0 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
104f0 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
10500 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
10510 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
10520 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
10530 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
10540 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
10550 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
10560 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
10570 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
10580 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
10590 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
105a0 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
105b0 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
105c0 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
105d0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
105e0 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
105f0 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
10600 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
10610 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
10620 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
10630 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
10640 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
10650 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
10660 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
10670 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
10680 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
10690 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
106a0 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
106b0 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
106c0 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
106d0 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
106e0 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
106f0 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
10700 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
10710 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
10720 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
10730 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
10740 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
10750 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
10760 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
10770 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
10780 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
10790 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
107a0 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
107b0 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
107c0 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
107d0 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
107e0 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
107f0 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
10800 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
10810 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
10820 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
10830 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
10840 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
10850 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
10860 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
10870 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
10880 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
10890 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
108a0 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
108b0 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
108c0 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
108d0 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
108e0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
108f0 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
10900 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
10910 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
10920 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
10930 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
10940 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
10950 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
10960 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
10970 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
10980 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
10990 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
109a0 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
109b0 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
109c0 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
109d0 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
109e0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
109f0 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
10a00 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
10a10 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
10a20 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
10a30 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
10a40 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
10a50 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
10a60 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
10a70 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
10a80 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
10a90 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
10aa0 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
10ab0 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
10ac0 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
10ad0 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
10ae0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
10af0 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
10b00 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
10b10 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
10b20 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
10b30 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
10b40 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
10b50 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
10b60 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
10b70 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
10b80 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
10b90 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
10ba0 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
10bb0 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
10bc0 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
10bd0 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
10be0 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
10bf0 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
10c00 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
10c10 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
10c20 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
10c30 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
10c40 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
10c50 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
10c60 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
10c70 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
10c80 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
10c90 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
10ca0 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
10cb0 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
10cc0 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
10cd0 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
10ce0 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
10cf0 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
10d00 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
10d10 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
10d20 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
10d30 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
10d40 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
10d50 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
10d60 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
10d70 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
10d80 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
10d90 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
10da0 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
10db0 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
10dc0 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
10dd0 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
10de0 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
10df0 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
10e00 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
10e10 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
10e20 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
10e30 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
10e40 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
10e50 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
10e60 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
10e70 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
10e80 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
10e90 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
10ea0 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
10eb0 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
10ec0 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
10ed0 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
10ee0 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
10ef0 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
10f00 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
10f10 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
10f20 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
10f30 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
10f40 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
10f50 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
10f60 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
10f70 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
10f80 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
10f90 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
10fa0 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
10fb0 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
10fc0 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
10fd0 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
10fe0 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
10ff0 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
11000 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
11010 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
11020 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
11030 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
11040 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
11050 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
11060 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
11070 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
11080 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
11090 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
110a0 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
110b0 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
110c0 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
110d0 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
110e0 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
110f0 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
11100 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
11110 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
11120 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
11130 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
11140 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
11150 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
11160 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
11170 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
11180 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
11190 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
111a0 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
111b0 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
111c0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
111d0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
111e0 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
111f0 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
11200 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
11210 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
11220 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
11230 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
11240 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
11250 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
11260 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
11270 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
11280 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
11290 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
112a0 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
112b0 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
112c0 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
112d0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
112e0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
112f0 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
11300 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
11310 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
11320 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
11330 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
11340 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
11350 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
11360 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
11370 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
11380 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
11390 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
113a0 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
113b0 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
113c0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
113d0 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
113e0 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
113f0 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
11400 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
11410 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
11420 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
11430 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
11440 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
11450 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
11460 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
11470 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
11480 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
11490 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
114a0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
114b0 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
114c0 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
114d0 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
114e0 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
114f0 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
11500 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
11510 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
11520 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
11530 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
11540 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
11550 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
11560 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
11570 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
11580 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
11590 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
115a0 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
115b0 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
115c0 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
115d0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
115e0 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
115f0 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
11600 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
11610 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
11620 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
11630 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
11640 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
11650 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
11660 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
11670 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
11680 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
11690 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
116a0 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
116b0 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
116c0 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
116d0 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
116e0 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
116f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
11700 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
11710 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
11720 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
11730 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
11740 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
11750 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
11760 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
11770 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
11780 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
11790 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
117a0 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
117b0 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
117c0 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
117d0 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
117e0 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
117f0 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
11800 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
11810 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
11820 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
11830 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
11840 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
11850 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
11860 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
11870 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
11880 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
11890 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
118a0 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
118b0 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
118c0 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
118d0 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
118e0 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
118f0 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
11900 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
11910 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
11920 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
11930 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
11940 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
11950 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
11960 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
11970 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
11980 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
11990 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
119a0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
119b0 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
119c0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
119d0 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
119e0 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
119f0 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
11a00 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
11a10 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
11a20 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
11a30 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
11a40 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
11a50 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
11a60 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
11a70 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
11a80 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
11a90 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
11aa0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
11ab0 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
11ac0 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
11ad0 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
11ae0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
11af0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
11b00 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
11b10 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
11b20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11b30 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
11b40 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
11b50 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
11b60 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
11b70 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
11b80 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
11b90 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
11ba0 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
11bb0 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
11bc0 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
11bd0 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
11be0 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
11bf0 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
11c00 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
11c10 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
11c20 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
11c30 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
11c40 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
11c50 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
11c60 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
11c70 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
11c80 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
11c90 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
11ca0 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
11cb0 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
11cc0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
11cd0 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
11ce0 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
11cf0 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
11d00 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
11d10 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
11d20 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
11d30 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
11d40 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
11d50 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65  ven on the corre
11d60 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
11d70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
11d80 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
11d90 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
11da0 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
11db0 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
11dc0 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
11dd0 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
11de0 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
11df0 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
11e00 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
11e10 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
11e20 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
11e30 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
11e40 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
11e50 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
11e60 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
11e70 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
11e80 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
11e90 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
11ea0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
11eb0 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
11ec0 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
11ed0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
11ee0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
11ef0 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
11f00 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
11f10 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
11f20 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
11f30 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
11f40 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
11f50 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
11f60 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
11f70 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
11f80 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
11f90 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
11fa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
11fb0 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
11fc0 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
11fd0 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
11fe0 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
11ff0 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
12000 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
12010 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
12020 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
12030 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
12040 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
12050 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
12060 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
12070 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
12080 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
12090 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
120a0 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
120b0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
120c0 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
120d0 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
120e0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
120f0 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
12100 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
12110 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
12120 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
12130 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
12140 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
12150 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
12160 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
12170 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
12180 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
12190 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
121a0 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
121b0 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
121c0 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
121d0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
121e0 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
121f0 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
12200 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
12210 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
12220 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
12230 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12240 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
12250 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
12260 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
12270 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
12280 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
12290 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
122a0 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
122b0 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
122c0 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
122d0 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
122e0 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
122f0 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
12300 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12310 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
12320 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
12330 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
12340 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
12350 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
12360 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
12370 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
12380 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
12390 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
123a0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
123b0 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
123c0 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
123d0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
123e0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
123f0 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
12400 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
12410 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
12420 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12430 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
12440 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
12450 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12460 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
12470 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
12480 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
12490 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
124a0 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
124b0 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
124c0 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
124d0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
124e0 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
124f0 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
12500 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
12510 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
12520 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
12530 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
12540 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
12550 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
12560 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
12570 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
12580 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
12590 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
125a0 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
125b0 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
125c0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
125d0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
125e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
125f0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
12600 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
12610 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
12620 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
12630 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
12640 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12650 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
12660 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
12670 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
12680 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
12690 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
126a0 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
126b0 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
126c0 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
126d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
126e0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
126f0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
12700 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12710 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
12720 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
12730 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
12740 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
12750 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
12760 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
12770 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
12780 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
12790 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
127a0 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
127b0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
127c0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
127d0 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
127e0 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
127f0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
12800 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
12810 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
12820 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
12830 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
12840 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
12850 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
12860 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
12870 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
12880 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12890 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
128a0 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
128b0 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
128c0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
128d0 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
128e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
128f0 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
12900 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
12910 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
12920 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
12930 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
12940 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
12950 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
12960 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
12970 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
12980 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
12990 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
129a0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
129b0 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
129c0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
129d0 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
129e0 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
129f0 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
12a00 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
12a10 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
12a20 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
12a30 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
12a40 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
12a50 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
12a60 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
12a70 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
12a80 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
12a90 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
12aa0 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
12ab0 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
12ac0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
12ad0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
12ae0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
12af0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
12b00 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
12b10 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
12b20 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
12b30 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
12b40 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
12b50 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
12b60 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
12b70 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
12b80 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
12b90 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
12ba0 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
12bb0 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
12bc0 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
12bd0 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
12be0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
12bf0 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
12c00 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
12c10 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
12c20 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
12c30 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
12c40 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
12c50 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
12c60 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
12c70 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
12c80 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
12c90 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
12ca0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
12cb0 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
12cc0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
12cd0 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
12ce0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
12cf0 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
12d00 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
12d10 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
12d20 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
12d30 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
12d40 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
12d50 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
12d60 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
12d70 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
12d80 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
12d90 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12da0 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
12db0 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
12dc0 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
12dd0 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
12de0 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
12df0 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
12e00 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
12e10 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
12e20 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
12e30 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
12e40 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
12e50 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
12e60 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
12e70 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
12e80 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
12e90 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
12ea0 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
12eb0 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
12ec0 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
12ed0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
12ee0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
12ef0 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
12f00 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
12f10 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
12f20 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
12f30 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
12f40 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
12f50 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
12f60 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
12f70 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
12f80 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
12f90 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
12fa0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
12fb0 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
12fc0 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
12fd0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
12fe0 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49  failure..*/.SQLI
12ff0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
13000 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f  e3_initialize(vo
13010 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
13020 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  int sqlite3_shut
13030 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  down(void);.SQLI
13040 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
13050 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29  e3_os_init(void)
13060 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
13070 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
13080 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
13090 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
130a0 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
130b0 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
130c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
130d0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
130e0 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
130f0 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
13100 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
13110 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
13120 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
13130 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
13140 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
13150 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
13160 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
13170 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
13180 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
13190 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
131a0 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
131b0 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
131c0 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
131d0 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
131e0 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
131f0 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
13200 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
13210 2a 2a 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c  **.** <b>The sql
13220 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
13230 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74  terface is not t
13240 68 72 65 61 64 73 61 66 65 2e 20 54 68 65 20 61  hreadsafe. The a
13250 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
13260 73 74 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e  st ensure that n
13270 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
13280 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
13290 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
132a0 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
132b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
132c0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e   is running.</b>
132d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
132e0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
132f0 72 66 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  rface.** may onl
13300 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
13310 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
13320 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
13330 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
13340 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
13350 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
13360 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
13370 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
13380 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
13390 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
133a0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
133b0 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
133c0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
133d0 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
133e0 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
133f0 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
13400 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
13410 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
13420 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
13430 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
13440 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
13450 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
13460 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
13470 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
13480 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
13490 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
134a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
134b0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
134c0 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
134d0 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
134e0 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
134f0 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
13500 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
13510 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
13520 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
13530 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
13540 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
13550 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
13560 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
13570 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
13580 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
13590 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
135a0 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
135b0 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
135c0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
135d0 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
135e0 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
135f0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
13600 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
13610 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
13620 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
13630 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
13640 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
13650 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e   int sqlite3_con
13660 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
13670 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13680 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
13690 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
136a0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
136b0 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  3.**.** The sqli
136c0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
136d0 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
136e0 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67  d to make config
136f0 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
13700 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73  es to a [databas
13710 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
13720 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73  The interface is
13730 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b   similar to.** [
13740 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13750 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68  ] except that th
13760 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20  e changes apply 
13770 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b  to a single.** [
13780 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13790 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20  ion] (specified 
137a0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
137b0 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  ument)..**.** Th
137c0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
137d0 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  t to sqlite3_db_
137e0 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20  config(D,V,...) 
137f0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   is the.** [SQLI
13800 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
13810 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72  ASIDE | configur
13820 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e  ation verb] - an
13830 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a   integer code .*
13840 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  * that indicates
13850 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20   what aspect of 
13860 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
13870 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69  nnection] is bei
13880 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a  ng configured..*
13890 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67  * Subsequent arg
138a0 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65  uments vary depe
138b0 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e  nding on the con
138c0 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e  figuration verb.
138d0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f  .**.** ^Calls to
138e0 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
138f0 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49  ig() return SQLI
13900 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c  TE_OK if and onl
13910 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  y if.** the call
13920 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73   is considered s
13930 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51  uccessful..*/.SQ
13940 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
13950 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
13960 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
13970 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
13980 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
13990 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
139a0 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
139b0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
139c0 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
139d0 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
139e0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
139f0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
13a00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
13a10 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
13a20 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
13a30 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
13a40 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
13a50 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
13a60 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
13a70 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
13a80 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
13a90 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
13aa0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13ab0 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
13ac0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
13ad0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
13ae0 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
13af0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13b00 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
13b10 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
13b20 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
13b30 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
13b40 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
13b50 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
13b60 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
13b70 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
13b80 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
13b90 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
13ba0 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
13bb0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
13bc0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
13bd0 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
13be0 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
13bf0 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
13c00 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
13c10 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
13c20 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
13c30 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
13c40 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
13c50 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
13c60 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
13c70 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
13c80 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
13c90 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
13ca0 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
13cb0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
13cc0 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
13cd0 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
13ce0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
13cf0 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
13d00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13d10 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
13d20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
13d30 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
13d40 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
13d50 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
13d60 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
13d70 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
13d80 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
13d90 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
13da0 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
13db0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
13dc0 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
13dd0 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
13de0 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
13df0 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
13e00 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
13e10 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
13e20 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
13e30 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
13e40 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
13e50 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
13e60 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
13e70 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
13e80 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
13e90 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
13ea0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
13eb0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
13ec0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
13ed0 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
13ee0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
13ef0 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
13f00 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
13f10 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
13f20 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
13f30 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
13f40 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
13f50 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
13f60 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
13f70 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
13f80 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
13f90 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
13fa0 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
13fb0 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
13fc0 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
13fd0 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
13fe0 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
13ff0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
14000 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
14010 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
14020 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
14030 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
14040 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
14050 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
14060 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
14070 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
14080 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
14090 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
140a0 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
140b0 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
140c0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
140d0 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
140e0 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
140f0 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
14100 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
14110 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
14120 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
14130 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
14140 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
14150 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
14160 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
14170 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
14180 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
14190 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
141a0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
141b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
141c0 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
141d0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
141e0 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
141f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
14200 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
14210 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
14220 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
14230 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
14240 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
14250 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
14260 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
14270 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
14280 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
14290 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
142a0 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
142b0 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
142c0 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
142d0 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
142e0 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
142f0 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
14300 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
14310 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
14320 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
14330 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
14340 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
14350 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
14360 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
14370 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
14380 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
14390 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
143a0 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
143b0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
143c0 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
143d0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
143e0 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
143f0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
14400 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
14410 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
14420 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
14430 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
14440 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
14450 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
14460 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
14470 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
14480 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
14490 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
144a0 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
144b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
144c0 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
144d0 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
144e0 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
144f0 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
14500 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
14510 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
14520 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
14530 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
14540 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
14550 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
14560 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
14570 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
14580 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
14590 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
145a0 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
145b0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
145c0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
145d0 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
145e0 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
145f0 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
14600 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
14610 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
14620 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
14630 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
14640 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
14650 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
14660 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
14670 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
14680 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
14690 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
146a0 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
146b0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
146c0 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
146d0 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
146e0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
146f0 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
14700 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
14710 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
14720 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
14730 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
14740 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
14750 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
14760 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
14770 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
14780 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
14790 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
147a0 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
147b0 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
147c0 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
147d0 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
147e0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
147f0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
14800 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
14810 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
14820 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
14830 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
14840 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
14850 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
14860 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
14870 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
14880 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
14890 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
148a0 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
148b0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
148c0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
148d0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
148e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
148f0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
14900 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
14910 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
14920 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
14930 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
14940 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
14950 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
14960 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
14970 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
14980 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
14990 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
149a0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
149b0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
149c0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
149d0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
149e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
149f0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
14a00 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
14a10 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
14a20 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
14a30 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
14a40 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
14a50 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
14a60 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
14a70 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
14a80 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14a90 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
14aa0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
14ab0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
14ac0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
14ad0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
14ae0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
14af0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
14b00 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
14b10 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
14b20 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
14b30 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
14b40 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
14b50 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
14b60 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
14b70 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
14b80 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
14b90 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
14ba0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
14bb0 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
14bc0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
14bd0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
14be0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
14bf0 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
14c00 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
14c10 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
14c20 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
14c30 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
14c40 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
14c50 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
14c60 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
14c70 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
14c80 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
14c90 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
14ca0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
14cb0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
14cc0 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
14cd0 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
14ce0 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
14cf0 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
14d00 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
14d10 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
14d20 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
14d30 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
14d40 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
14d50 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14d60 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
14d70 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14d80 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
14d90 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14da0 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
14db0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14dc0 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
14dd0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
14de0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
14df0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
14e00 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
14e10 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
14e20 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
14e30 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
14e40 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
14e50 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
14e60 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
14e70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
14e80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
14e90 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
14ea0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
14eb0 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
14ec0 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
14ed0 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
14ee0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
14ef0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
14f00 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
14f10 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
14f20 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
14f30 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
14f40 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
14f50 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
14f60 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
14f70 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
14f80 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
14f90 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
14fa0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
14fb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14fc0 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
14fd0 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
14fe0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
14ff0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
15000 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
15010 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
15020 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
15030 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
15040 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
15050 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
15060 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
15070 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
15080 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
15090 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
150a0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
150b0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
150c0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
150d0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
150e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
150f0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
15100 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15110 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
15120 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15130 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
15140 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
15150 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
15160 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
15170 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
15180 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
15190 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
151a0 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
151b0 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
151c0 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
151d0 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
151e0 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
151f0 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
15200 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
15210 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
15220 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
15230 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
15240 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
15250 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
15260 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
15270 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
15280 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
15290 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
152a0 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
152b0 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
152c0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
152d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
152e0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
152f0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
15300 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
15310 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
15320 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
15330 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
15340 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
15350 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
15360 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
15370 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
15380 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
15390 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
153a0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
153b0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
153c0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
153d0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
153e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
153f0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
15400 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
15410 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
15420 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
15430 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
15440 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15450 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
15460 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
15470 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
15480 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
15490 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
154a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
154b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
154c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
154d0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
154e0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
154f0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
15500 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15510 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
15520 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15530 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
15540 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
15550 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
15560 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
15570 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
15580 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
15590 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
155a0 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
155b0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
155c0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
155d0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
155e0 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
155f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15600 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
15610 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
15620 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
15630 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
15640 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
15650 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
15660 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
15670 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
15680 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
15690 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
156a0 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
156b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
156c0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
156d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
156e0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
156f0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
15700 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15710 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  TMALLOC option t
15720 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
15730 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
15740 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
15750 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
15760 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
15770 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
15780 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  re..** The [sqli
15790 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
157a0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
157b0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
157c0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
157d0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
157e0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
157f0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
15800 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
15810 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
15820 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
15830 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
15840 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
15850 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
15860 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
15870 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
15880 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
15890 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
158a0 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
158b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
158c0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
158d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
158e0 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
158f0 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
15900 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
15910 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  S option takes s
15920 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
15930 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69  f type int,.** i
15940 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
15950 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
15960 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
15970 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
15980 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  n of.** memory a
15990 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
159a0 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
159b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
159c0 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a  tatistics are.**
159d0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66   disabled, the f
159e0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
159f0 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
15a00 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
15a10 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
15a20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
15a30 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
15a40 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
15a50 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
15a60 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
15a70 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
15a80 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
15a90 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
15aa0 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20  _status64()].** 
15ab0 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
15ac0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
15ad0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
15ae0 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
15af0 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
15b00 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
15b10 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
15b20 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
15b30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
15b40 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
15b50 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
15b60 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
15b70 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
15b80 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
15b90 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
15ba0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15bb0 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
15bc0 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
15bd0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
15be0 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  CH option specif
15bf0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
15c00 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  ory buffer.** th
15c10 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
15c20 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65  e for scratch me
15c30 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61  mory.  ^(There a
15c40 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
15c50 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f  ts.** to SQLITE_
15c60 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20  CONFIG_SCRATCH: 
15c70 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
15c80 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
15c90 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
15ca0 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
15cb0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
15cc0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
15cd0 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
15ce0 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
15cf0 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
15d00 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
15d10 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
15d20 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
15d30 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ).)^.** The firs
15d40 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
15d50 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
15d60 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
15d70 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
15d80 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
15d90 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
15da0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f   ^SQLite will no
15db0 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20  t use more than 
15dc0 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
15dd0 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a  ers per thread..
15de0 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
15df0 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20  never request a 
15e00 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
15e10 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
15e20 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
15e30 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
15e40 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  ze..** ^If SQLit
15e50 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
15e60 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
15e70 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
15e80 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
15e90 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
15ea0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
15eb0 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
15ec0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
15ed0 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
15ee0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
15ef0 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68  eeded.<p>.** ^Wh
15f00 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  en the applicati
15f10 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20  on provides any 
15f20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63  amount of scratc
15f30 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a  h memory using.*
15f40 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
15f50 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20  SCRATCH, SQLite 
15f60 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61  avoids unnecessa
15f70 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c  ry large.** [sql
15f80 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70  ite3_malloc|heap
15f90 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a   allocations]..*
15fa0 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20  * This can help 
15fb0 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72  [Robson proof|pr
15fc0 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  event memory all
15fd0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  ocation failures
15fe0 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a  ] due to heap.**
15ff0 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69   fragmentation i
16000 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62  n low-memory emb
16010 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a  edded systems..*
16020 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
16030 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
16040 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
16050 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
16060 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
16070 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
16080 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
16090 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
160a0 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a   a memory pool.*
160b0 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  * that SQLite ca
160c0 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64 61  n use for the da
160d0 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
160e0 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
160f0 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65  lt page.** cache
16100 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
16110 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
16120 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
16130 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e  is a no-op if an
16140 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
16150 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ine page.** cach
16160 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
16170 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67   is loaded using
16180 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
16190 46 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a  FIG_PCACHE2]..**
161a0 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
161b0 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
161c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
161d0 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65  ECACHE: A pointe
161e0 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61  r to.** 8-byte a
161f0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70  ligned memory (p
16200 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f  Mem), the size o
16210 66 20 65 61 63 68 20 70 61 67 65 20 63 61 63 68  f each page cach
16220 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20  e line (sz),.** 
16230 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
16240 66 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e  f cache lines (N
16250 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67  )..** The sz arg
16260 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
16270 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
16280 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65  largest database
16290 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65   page.** (a powe
162a0 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e  r of two between
162b0 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29 20   512 and 65536) 
162c0 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20  plus some extra 
162d0 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a  bytes for each.*
162e0 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
162f0 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65  ^The number of e
16300 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64 65  xtra bytes neede
16310 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68 65  d by the page he
16320 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64  ader.** can be d
16330 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20  etermined using 
16340 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
16350 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a  CACHE_HDRSZ]..**
16360 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
16370 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
16380 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
16390 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61  ** for the sz pa
163a0 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61  rameter to be la
163b0 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73  rger than necess
163c0 61 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a  ary.  The pMem.*
163d0 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
163e0 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
163f0 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f   pointer or a po
16400 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
16410 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c  te.** aligned bl
16420 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66  ock of memory of
16430 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
16440 79 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a  ytes, otherwise.
16450 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  ** subsequent be
16460 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
16470 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d  ned..** ^When pM
16480 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20  em is not NULL, 
16490 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69  SQLite will stri
164a0 76 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65  ve to use the me
164b0 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a  mory provided.**
164c0 20 74 6f 20 73 61 74 69 73 66 79 20 70 61 67 65   to satisfy page
164d0 20 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61   cache needs, fa
164e0 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73  lling back to [s
164f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16500 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61   if.** a page ca
16510 63 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67  che line is larg
16520 65 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73  er than sz bytes
16530 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68   or if all of th
16540 65 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a  e pMem buffer.**
16550 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a   is exhausted..*
16560 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55  * ^If pMem is NU
16570 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d  LL and N is non-
16580 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20  zero, then each 
16590 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
165a0 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69  ion.** does an i
165b0 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f  nitial bulk allo
165c0 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20  cation for page 
165d0 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  cache memory.** 
165e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
165f0 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65  lloc()] sufficie
16600 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c  nt for N cache l
16610 69 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73  ines if N is pos
16620 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d  itive or.** of -
16630 31 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20  1024*N bytes if 
16640 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e  N is negative, .
16650 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a   ^If additional.
16660 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ** page cache me
16670 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62  mory is needed b
16680 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
16690 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 69 6e  ovided by the in
166a0 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74  itial.** allocat
166b0 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ion, then SQLite
166c0 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
166d0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61  3_malloc()] sepa
166e0 72 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a  rately for each.
166f0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61  ** additional ca
16700 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a  che line. </dd>.
16710 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16720 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74  ONFIG_HEAP]] <dt
16730 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  >SQLITE_CONFIG_H
16740 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAP</dt>.** <dd>
16750 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
16760 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
16770 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
16780 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
16790 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65   .** that SQLite
167a0 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c   will use for al
167b0 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
167c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
167d0 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f  on needs.** beyo
167e0 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65  nd those provide
167f0 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  d for by [SQLITE
16800 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
16810 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   and.** [SQLITE_
16820 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
16830 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54  ]..** ^The SQLIT
16840 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70  E_CONFIG_HEAP op
16850 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61  tion is only ava
16860 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65  ilable if SQLite
16870 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20   is compiled.** 
16880 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c  with either [SQL
16890 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
168a0 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45  S3] or [SQLITE_E
168b0 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61  NABLE_MEMSYS5] a
168c0 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  nd returns.** [S
168d0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
168e0 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73  invoked otherwis
168f0 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65  e..** ^There are
16900 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
16910 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
16920 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d  G_HEAP:.** An 8-
16930 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69  byte aligned poi
16940 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f  nter to the memo
16950 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  ry,.** the numbe
16960 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
16970 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c  e memory buffer,
16980 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d   and the minimum
16990 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
169a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72  ..** ^If the fir
169b0 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
169c0 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
169d0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51  is NULL, then SQ
169e0 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20  Lite reverts.** 
169f0 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66  to using its def
16a00 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
16a10 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65  cator (the syste
16a20 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65  m malloc() imple
16a30 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75  mentation),.** u
16a40 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72  ndoing any prior
16a50 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
16a60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
16a70 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a  LLOC].  ^If the.
16a80 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  ** memory pointe
16a90 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  r is not NULL th
16aa0 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
16ab0 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
16ac0 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
16ad0 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
16ae0 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
16af0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
16b00 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
16b10 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
16b20 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
16b30 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
16b40 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
16b50 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
16b60 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
16b70 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
16b80 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
16b90 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
16ba0 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70  tion size is cap
16bb0 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65  ped at 2**12. Re
16bc0 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a  asonable values.
16bd0 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d  ** for the minim
16be0 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
16bf0 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f  ze are 2**5 thro
16c00 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a  ugh 2**8.</dd>.*
16c10 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16c20 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74  NFIG_MUTEX]] <dt
16c30 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
16c40 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
16c50 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
16c60 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69  ONFIG_MUTEX opti
16c70 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
16c80 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
16c90 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
16ca0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
16cb0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
16cc0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
16cd0 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65  tructure..** The
16ce0 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
16cf0 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20  ies alternative 
16d00 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
16d10 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
16d20 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20  sed.** in place 
16d30 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
16d40 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
16d50 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
16d60 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
16d70 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
16d80 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
16d90 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
16da0 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
16db0 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
16dc0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
16dd0 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
16de0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
16df0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
16e00 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
16e10 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
16e20 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
16e30 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
16e40 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
16e50 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
16e60 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
16e70 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
16e80 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
16e90 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
16ea0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
16eb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
16ec0 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
16ed0 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
16ee0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
16ef0 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
16f00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16f10 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  _GETMUTEX]] <dt>
16f20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16f30 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
16f40 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
16f50 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
16f60 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
16f70 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
16f80 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f  which.** is a po
16f90 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
16fa0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
16fb0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
16fc0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
16fd0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
16fe0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
16ff0 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
17000 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
17010 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
17020 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
17030 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
17040 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
17050 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
17060 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
17070 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
17080 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
17090 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
170a0 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
170b0 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
170c0 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
170d0 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
170e0 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
170f0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
17100 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
17110 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
17120 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
17130 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
17140 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
17150 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
17160 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
17170 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
17180 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
17190 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
171a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
171b0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
171c0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
171d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
171e0 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
171f0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
17200 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
17210 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
17220 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c  KASIDE]] <dt>SQL
17230 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
17240 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
17250 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
17260 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
17270 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
17280 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
17290 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65  determine.** the
172a0 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66   default size of
172b0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
172c0 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62  y on each [datab
172d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
172e0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
172f0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
17300 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
17310 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
17320 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
17330 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
17340 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
17350 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
17360 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17370 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f  on.)^  ^(SQLITE_
17380 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
17390 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e  .** sets the <i>
173a0 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b  default</i> look
173b0 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20  aside size. The 
173c0 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
173d0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f  _LOOKASIDE].** o
173e0 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65  ption to [sqlite
173f0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
17400 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
17410 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
17420 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
17430 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
17440 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
17450 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
17460 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17470 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
17480 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
17490 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
174a0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
174b0 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e  G_PCACHE2 option
174c0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
174d0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
174e0 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
174f0 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  to an [sqlite3_p
17500 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
17510 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
17520 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ject specifies.*
17530 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  * the interface 
17540 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
17550 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
17560 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c  ation.)^.** ^SQL
17570 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
17580 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
17590 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
175a0 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a  ] object.</dd>.*
175b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
175c0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
175d0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
175e0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
175f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
17600 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17610 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f  GETPCACHE2 optio
17620 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
17630 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a   argument which.
17640 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ** is a pointer 
17650 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  to an [sqlite3_p
17660 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
17670 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20  object.  SQLite 
17680 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65  copies of.** the
17690 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63 61   current page ca
176a0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
176b0 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a  on into that obj
176c0 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ect.)^ </dd>.**.
176d0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
176e0 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c  IG_LOG]] <dt>SQL
176f0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f  ITE_CONFIG_LOG</
17700 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20  dt>.** <dd> The 
17710 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
17720 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  G option is used
17730 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68   to configure th
17740 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62  e SQLite.** glob
17750 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a  al [error log]..
17760 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f  ** (^The SQLITE_
17770 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
17780 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
17790 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
177a0 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
177b0 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
177c0 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
177d0 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
177e0 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
177f0 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
17800 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
17810 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
17820 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
17830 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
17840 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
17850 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
17860 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
17870 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
17880 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
17890 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
178a0 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
178b0 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
178c0 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
178d0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
178e0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
178f0 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
17900 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
17910 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
17920 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
17930 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
17940 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
17950 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
17960 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
17970 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
17980 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
17990 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
179a0 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
179b0 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
179c0 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
179d0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
179e0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
179f0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
17a00 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
17a10 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
17a20 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
17a30 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
17a40 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
17a50 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
17a60 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
17a70 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
17a80 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
17a90 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
17aa0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
17ab0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
17ac0 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
17ad0 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
17ae0 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
17af0 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
17b00 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
17b10 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
17b20 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
17b30 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
17b40 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
17b50 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
17b60 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
17b70 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
17b80 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
17b90 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
17ba0 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
17bb0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
17bc0 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  RI]] <dt>SQLITE_
17bd0 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64  CONFIG_URI.** <d
17be0 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  d>^(The SQLITE_C
17bf0 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e  ONFIG_URI option
17c00 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
17c10 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
17c20 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d   int..** If non-
17c30 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68  zero, then URI h
17c40 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
17c50 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20  lly enabled. If 
17c60 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
17c70 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55   zero,.** then U
17c80 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
17c90 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
17ca0 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64  .)^ ^If URI hand
17cb0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
17cc0 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c  .** enabled, all
17cd0 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65   filenames passe
17ce0 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d to [sqlite3_op
17cf0 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
17d00 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  open_v2()],.** [
17d10 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
17d20 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65  ] or.** specifie
17d30 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54  d as part of [AT
17d40 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61  TACH] commands a
17d50 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
17d60 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65  s URIs, regardle
17d70 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72  ss.** of whether
17d80 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c   or not the [SQL
17d90 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
17da0 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
17db0 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
17dc0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
17dd0 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67  ned. ^If it is g
17de0 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
17df0 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
17e00 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
17e10 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
17e20 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
17e30 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
17e40 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
17e50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
17e60 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64  s opened. ^(By d
17e70 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64  efault, URI hand
17e80 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
17e90 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68  .** disabled. Th
17ea0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
17eb0 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62  may be changed b
17ec0 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68  y compiling with
17ed0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
17ee0 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20  USE_URI] symbol 
17ef0 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  defined.)^.**.**
17f00 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
17f10 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
17f20 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SCAN]] <dt>SQLIT
17f30 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
17f40 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20  G_INDEX_SCAN.** 
17f50 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The 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 20 6f 70 74 69 6f  INDEX_SCAN optio
17f80 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
17f90 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75   integer.** argu
17fa0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e  ment which is in
17fb0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62  terpreted as a b
17fc0 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20  oolean in order 
17fd0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
17fe0 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20  able.** the use 
17ff0 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69  of covering indi
18000 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62  ces for full tab
18010 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20  le scans in the 
18020 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e  query optimizer.
18030 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
18040 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65   setting is dete
18050 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65  rmined.** by the
18060 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43   [SQLITE_ALLOW_C
18070 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
18080 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  AN] compile-time
18090 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22   option, or is "
180a0 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63  on".** if that c
180b0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
180c0 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  on is omitted..*
180d0 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f  * The ability to
180e0 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65   disable the use
180f0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
18100 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
18110 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20  ble scans.** is 
18120 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63  because some inc
18130 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c  orrectly coded l
18140 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f  egacy applicatio
18150 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63  ns might malfunc
18160 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65  tion.** when the
18170 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73   optimization is
18180 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69   enabled.  Provi
18190 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79  ding the ability
181a0 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74   to.** disable t
181b0 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
181c0 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72  allows the older
181d0 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74  , buggy applicat
181e0 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b  ion code to work
181f0 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e  .** without chan
18200 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77  ge even with new
18210 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
18220 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  QLite..**.** [[S
18230 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
18240 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43  CHE]] [[SQLITE_C
18250 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d  ONFIG_GETPCACHE]
18260 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
18270 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e  CONFIG_PCACHE an
18280 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d SQLITE_CONFIG_
18290 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64  GETPCACHE.** <dd
182a0 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20  > These options 
182b0 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64  are obsolete and
182c0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
182d0 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e  sed by new code.
182e0 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74  .** They are ret
182f0 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
18300 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
18310 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f  y but are now no
18320 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  -ops..** </dd>.*
18330 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
18340 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a  NFIG_SQLLOG]].**
18350 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
18360 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64  IG_SQLLOG.** <dd
18370 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  >This option is 
18380 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
18390 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70  f sqlite is comp
183a0 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
183b0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
183c0 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63  SQLLOG] pre-proc
183d0 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69  essor macro defi
183e0 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61  ned. The first a
183f0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a  rgument should.*
18400 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  * be a pointer t
18410 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
18420 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69  type void(*)(voi
18430 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73  d*,sqlite3*,cons
18440 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a  t char*, int)..*
18450 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f  * The second sho
18460 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28  uld be of type (
18470 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c  void*). The call
18480 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
18490 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a  by the library.*
184a0 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72  * in three separ
184b0 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ate circumstance
184c0 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  s, identified by
184d0 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
184e0 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  d as the.** four
184f0 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66  th parameter. If
18500 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
18510 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e  meter is 0, then
18520 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18530 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73  nnection.** pass
18540 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
18550 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75   argument has ju
18560 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  st been opened. 
18570 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
18580 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  nt.** points to 
18590 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e  a buffer contain
185a0 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ing the name of 
185b0 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
185c0 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a  e file. If the.*
185d0 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
185e0 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68  er is 1, then th
185f0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
18600 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70  that the third p
18610 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e  arameter.** poin
18620 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62  ts to has just b
18630 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72  een executed. Or
18640 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20  , if the fourth 
18650 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20  parameter is 2, 
18660 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e  then.** the conn
18670 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73  ection being pas
18680 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
18690 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62  d parameter is b
186a0 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65  eing closed. The
186b0 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
186c0 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55  ter is passed NU
186d0 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e  LL In this case.
186e0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20    An example of 
186f0 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f  using this.** co
18700 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
18710 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69  on can be seen i
18720 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c  n the "test_sqll
18730 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c  og.c" source fil
18740 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f  e in.** the cano
18750 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75  nical SQLite sou
18760 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a  rce tree.</dd>.*
18770 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
18780 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  NFIG_MMAP_SIZE]]
18790 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
187a0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a  ONFIG_MMAP_SIZE.
187b0 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43  ** <dd>^SQLITE_C
187c0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
187d0 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74  takes two 64-bit
187e0 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65   integer (sqlite
187f0 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a  3_int64) values.
18800 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20  ** that are the 
18810 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a  default mmap siz
18820 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66  e limit (the def
18830 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72  ault setting for
18840 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  .** [PRAGMA mmap
18850 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20  _size]) and the 
18860 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
18870 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e  mmap size limit.
18880 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
18890 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20   setting can be 
188a0 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61  overridden by ea
188b0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
188c0 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  ection using.** 
188d0 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47  either the [PRAG
188e0 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f  MA mmap_size] co
188f0 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69  mmand, or by usi
18900 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
18910 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
18920 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e  E] file control.
18930 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20    ^(The maximum 
18940 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
18950 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c  e.** will be sil
18960 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
18970 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20  if necessary so 
18980 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74  that it does not
18990 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63   exceed the.** c
189a0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69  ompile-time maxi
189b0 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65  mum mmap size se
189c0 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  t by the.** [SQL
189d0 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a  ITE_MAX_MMAP_SIZ
189e0 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
189f0 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66  option.)^.** ^If
18a00 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74   either argument
18a10 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20   to this option 
18a20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
18a30 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20  n that argument 
18a40 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f  is.** changed to
18a50 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d   its compile-tim
18a60 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  e default..**.**
18a70 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
18a80 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d  _WIN32_HEAPSIZE]
18a90 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
18aa0 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41  CONFIG_WIN32_HEA
18ab0 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68  PSIZE.** <dd>^Th
18ac0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18ad0 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f  WIN32_HEAPSIZE o
18ae0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
18af0 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
18b00 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
18b10 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74   for Windows wit
18b20 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49  h the [SQLITE_WI
18b30 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d  N32_MALLOC] pre-
18b40 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a  processor macro.
18b50 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c  ** defined. ^SQL
18b60 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
18b70 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20  _HEAPSIZE takes 
18b80 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65  a 32-bit unsigne
18b90 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a  d integer value.
18ba0 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65  ** that specifie
18bb0 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  s the maximum si
18bc0 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65  ze of the create
18bd0 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  d heap..**.** [[
18be0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
18bf0 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20  ACHE_HDRSZ]].** 
18c00 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
18c10 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a  G_PCACHE_HDRSZ.*
18c20 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
18c30 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
18c40 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b  HDRSZ option tak
18c50 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61  es a single para
18c60 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69  meter which.** i
18c70 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
18c80 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72  n integer and wr
18c90 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69  ites into that i
18ca0 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65  nteger the numbe
18cb0 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79  r of extra.** by
18cc0 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65 71  tes per page req
18cd0 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20 70  uired for each p
18ce0 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43  age in [SQLITE_C
18cf0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
18d00 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20  ..** The amount 
18d10 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20 72  of extra space r
18d20 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e  equired can chan
18d30 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ge depending on 
18d40 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a  the compiler,.**
18d50 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d   target platform
18d60 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  , and SQLite ver
18d70 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  sion..**.** [[SQ
18d80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53  LITE_CONFIG_PMAS
18d90 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  Z]].** <dt>SQLIT
18da0 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a  E_CONFIG_PMASZ.*
18db0 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54  * <dd>^The SQLIT
18dc0 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f  E_CONFIG_PMASZ o
18dd0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
18de0 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
18df0 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e  hich.** is an un
18e00 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61  signed integer a
18e10 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e  nd sets the "Min
18e20 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66  imum PMA Size" f
18e30 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65  or the multithre
18e40 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74  aded.** sorter t
18e50 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20  o that integer. 
18e60 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e   The default min
18e70 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73  imum PMA Size is
18e80 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
18e90 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d  SQLITE_SORTER_PM
18ea0 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ASZ] compile-tim
18eb0 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74  e option.  New t
18ec0 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63  hreads are launc
18ed0 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77  hed.** to help w
18ee0 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69  ith sort operati
18ef0 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68  ons when multith
18f00 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a  readed sorting.*
18f10 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73  * is enabled (us
18f20 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20  ing the [PRAGMA 
18f30 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64  threads] command
18f40 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74  ) and the amount
18f50 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74   of content.** t
18f60 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63 65  o be sorted exce
18f70 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69 7a  eds the page siz
18f80 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69  e times the mini
18f90 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50  mum of the.** [P
18fa0 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65  RAGMA cache_size
18fb0 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68  ] setting and th
18fc0 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  is value..**.** 
18fd0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
18fe0 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d  STMTJRNL_SPILL]]
18ff0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
19000 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
19010 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65  PILL.** <dd>^The
19020 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
19030 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70  TMTJRNL_SPILL op
19040 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
19050 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68  gle parameter wh
19060 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74  ich.** becomes t
19070 68 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f  he [statement jo
19080 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d  urnal] spill-to-
19090 64 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20  disk threshold. 
190a0 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20   .** [Statement 
190b0 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65  journals] are he
190c0 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74  ld in memory unt
190d0 69 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28 69  il their size (i
190e0 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65  n bytes).** exce
190f0 65 64 73 20 74 68 69 73 20 74 68 72 65 73 68 6f  eds this thresho
19100 6c 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69  ld, at which poi
19110 6e 74 20 74 68 65 79 20 61 72 65 20 77 72 69 74  nt they are writ
19120 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20  ten to disk..** 
19130 4f 72 20 69 66 20 74 68 65 20 74 68 72 65 73 68  Or if the thresh
19140 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65  old is -1, state
19150 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72  ment journals ar
19160 65 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a  e always held.**
19170 20 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20   exclusively in 
19180 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65  memory..** Since
19190 20 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20   many statement 
191a0 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62  journals never b
191b0 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74  ecome large, set
191c0 74 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a  ting the spill.*
191d0 2a 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61  * threshold to a
191e0 20 76 61 6c 75 65 20 73 75 63 68 20 61 73 20 36   value such as 6
191f0 34 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79  4KiB can greatly
19200 20 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75   reduce the amou
19210 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71  nt of.** I/O req
19220 75 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74  uired to support
19230 20 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62   statement rollb
19240 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61  ack..** The defa
19250 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ult value for th
19260 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f  is setting is co
19270 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a  ntrolled by the.
19280 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a  ** [SQLITE_STMTJ
19290 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69  RNL_SPILL] compi
192a0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
192b0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
192c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
192d0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20  G_SINGLETHREAD  
192e0 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  1  /* nil */.#de
192f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
19300 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20  IG_MULTITHREAD  
19310 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   2  /* nil */.#d
19320 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
19330 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20  FIG_SERIALIZED  
19340 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    3  /* nil */.#
19350 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
19360 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20  NFIG_MALLOC     
19370 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33     4  /* sqlite3
19380 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
19390 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
193a0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
193b0 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74       5  /* sqlit
193c0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
193d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
193e0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
193f0 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69         6  /* voi
19400 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
19410 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
19420 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
19430 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76  ACHE     7  /* v
19440 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
19450 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
19460 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
19470 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a  P          8  /*
19480 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74   void*, int nByt
19490 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64  e, int min */.#d
194a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
194b0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20  FIG_MEMSTATUS   
194c0 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20    9  /* boolean 
194d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
194e0 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20  E_CONFIG_MUTEX  
194f0 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c        10  /* sql
19500 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
19510 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
19520 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
19530 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a  MUTEX     11  /*
19540 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d   sqlite3_mutex_m
19550 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72  ethods* */./* pr
19560 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f  eviously SQLITE_
19570 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f  CONFIG_CHUNKALLO
19580 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f  C 12 which is no
19590 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64  w unused. */ .#d
195a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
195b0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
195c0 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20   13  /* int int 
195d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
195e0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
195f0 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d        14  /* no-
19600 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  op */.#define SQ
19610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
19620 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
19630 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65  no-op */.#define
19640 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
19650 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20  OG          16  
19660 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20  /* xFunc, void* 
19670 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19680 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20  E_CONFIG_URI    
19690 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74        17  /* int
196a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
196b0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
196c0 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71  2      18  /* sq
196d0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
196e0 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
196f0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19700 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20  GETPCACHE2   19 
19710 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
19720 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
19730 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19740 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
19750 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a  NDEX_SCAN 20  /*
19760 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
19770 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
19780 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f  LLOG       21  /
19790 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a  * xSqllog, void*
197a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
197b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
197c0 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71  IZE    22  /* sq
197d0 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c  lite3_int64, sql
197e0 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64  ite3_int64 */.#d
197f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
19800 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
19810 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69  ZE      23  /* i
19820 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66  nt nByte */.#def
19830 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
19840 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20  G_PCACHE_HDRSZ  
19850 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74        24  /* int
19860 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65   *psz */.#define
19870 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
19880 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20 20  MASZ            
19890 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e     25  /* unsign
198a0 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a  ed int szPma */.
198b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
198c0 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53  ONFIG_STMTJRNL_S
198d0 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a  PILL      26  /*
198e0 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f   int nByte */../
198f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
19900 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
19910 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  on Configuration
19920 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54   Options.**.** T
19930 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
19940 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
19950 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
19960 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
19970 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
19980 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
19990 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  nd argument to t
199a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  he [sqlite3_db_c
199b0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
199c0 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
199d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
199e0 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
199f0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
19a00 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
19a10 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
19a20 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
19a30 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
19a40 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
19a50 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
19a60 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
19a70 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
19a80 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
19a90 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
19aa0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
19ab0 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71  orked.  ^The [sq
19ac0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
19ad0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  )] interface wil
19ae0 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f  l return a.** no
19af0 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
19b00 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74  de] if a discont
19b10 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f  inued or unsuppo
19b20 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69  rted configurati
19b30 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20  on option.** is 
19b40 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  invoked..**.** <
19b50 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  dl>.** <dt>SQLIT
19b60 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
19b70 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
19b80 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
19b90 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74  akes three addit
19ba0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20  ional arguments 
19bb0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
19bc0 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64  he .** [lookasid
19bd0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
19be0 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  or] configuratio
19bf0 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62  n for the [datab
19c00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
19c10 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
19c20 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69  rgument (the thi
19c30 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
19c40 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
19c50 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f  ig()] is a.** po
19c60 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
19c70 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20  y buffer to use 
19c80 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  for lookaside me
19c90 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  mory..** ^The fi
19ca0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74  rst argument aft
19cb0 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42  er the SQLITE_DB
19cc0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
19cd0 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20   verb.** may be 
19ce0 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61  NULL in which ca
19cf0 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61  se SQLite will a
19d00 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c  llocate the.** l
19d10 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
19d20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71  itself using [sq
19d30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
19d40 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
19d50 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
19d60 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
19d70 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
19d80 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  ot.  ^The third 
19d90 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
19da0 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
19db0 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66  ts.  The size of
19dc0 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74   the buffer in t
19dd0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19de0 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65  t must be greate
19df0 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75  r than.** or equ
19e00 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63  al to the produc
19e10 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  t of the second 
19e20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65  and third argume
19e30 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  nts.  The buffer
19e40 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67  .** must be alig
19e50 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
19e60 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20   boundary.  ^If 
19e70 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
19e80 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45  ent to.** SQLITE
19e90 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
19ea0 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c  IDE is not a mul
19eb0 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69  tiple of 8, it i
19ec0 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20  s internally.** 
19ed0 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20  rounded down to 
19ee0 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72  the next smaller
19ef0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20   multiple of 8. 
19f00 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65   ^(The lookaside
19f10 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69   memory.** confi
19f20 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64  guration for a d
19f30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19f40 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63  on can only be c
19f50 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74  hanged when that
19f60 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
19f70 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
19f80 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20  using lookaside 
19f90 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74  memory, or in ot
19fa0 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65  her words.** whe
19fb0 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76  n the "current v
19fc0 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62  alue" returned b
19fd0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62  y.** [sqlite3_db
19fe0 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49  _status](D,[SQLI
19ff0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
1a000 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72  IDE],...) is zer
1a010 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  o..** Any attemp
1a020 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  t to change the 
1a030 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
1a040 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77   configuration w
1a050 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  hen lookaside.**
1a060 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73   memory is in us
1a070 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e  e leaves the con
1a080 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61  figuration uncha
1a090 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73  nged and returns
1a0a0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53   .** [SQLITE_BUS
1a0b0 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  Y].)^</dd>.**.**
1a0c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
1a0d0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
1a0e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
1a0f0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
1a100 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
1a110 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f  disable the enfo
1a120 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66  rcement of.** [f
1a130 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74  oreign key const
1a140 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20  raints].  There 
1a150 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
1a160 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
1a170 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
1a180 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
1a190 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
1a1a0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b   0 to disable FK
1a1b0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a   enforcement,.**
1a1c0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
1a1d0 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ble FK enforceme
1a1e0 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  nt or negative t
1a1f0 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72  o leave FK enfor
1a200 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e  cement.** unchan
1a210 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ged.  The second
1a220 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
1a230 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
1a240 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
1a250 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
1a260 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
1a270 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66  e whether FK enf
1a280 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20  orcement is off 
1a290 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  or on.** followi
1a2a0 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
1a2b0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a2c0 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
1a2d0 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
1a2e0 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
1a2f0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73  FK enforcement s
1a300 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
1a310 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
1a320 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
1a330 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1a340 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e  BLE_TRIGGER</dt>
1a350 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
1a360 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
1a370 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
1a380 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  le [CREATE TRIGG
1a390 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a  ER | triggers]..
1a3a0 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
1a3b0 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
1a3c0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
1a3d0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1a3e0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
1a3f0 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
1a400 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c  isable triggers,
1a410 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
1a420 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20  enable triggers 
1a430 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
1a440 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67  eave the setting
1a450 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54   unchanged..** T
1a460 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a470 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
1a480 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69   to an integer i
1a490 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  nto which.** is 
1a4a0 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
1a4b0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
1a4c0 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20  er triggers are 
1a4d0 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62  disabled or enab
1a4e0 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  led.** following
1a4f0 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
1a500 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a510 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
1a520 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
1a530 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72  hich case the tr
1a540 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73  igger setting is
1a550 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
1a560 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
1a570 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
1a580 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f  FIG_ENABLE_FTS3_
1a590 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a  TOKENIZER</dt>.*
1a5a0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
1a5b0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
1a5c0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
1a5d0 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e   the two-argumen
1a5e0 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  t.** version of 
1a5f0 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69  the [fts3_tokeni
1a600 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  zer()] function 
1a610 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f 66  which is part of
1a620 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66   the.** [FTS3] f
1a630 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20  ull-text search 
1a640 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e  engine extension
1a650 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
1a660 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
1a670 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
1a680 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
1a690 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
1a6a0 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
1a6b0 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f   disable fts3_to
1a6c0 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20  kenizer() or.** 
1a6d0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
1a6e0 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  le fts3_tokenize
1a6f0 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20  r() or negative 
1a700 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
1a710 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ting.** unchange
1a720 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
1a730 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
1a740 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
1a750 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
1a760 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
1a770 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
1a780 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f 74  e whether fts3_t
1a790 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61  okenizer is disa
1a7a0 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
1a7b0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
1a7c0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
1a7d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
1a7e0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
1a7f0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
1a800 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73 65   case the new se
1a810 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
1a820 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
1a830 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
1a840 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
1a850 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f  LE_LOAD_EXTENSIO
1a860 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  N</dt>.** <dd> ^
1a870 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
1a880 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
1a890 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71   disable the [sq
1a8a0 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
1a8b0 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  sion()].** inter
1a8c0 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74  face independent
1a8d0 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f  ly of the [load_
1a8e0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c  extension()] SQL
1a8f0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68   function..** Th
1a900 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  e [sqlite3_enabl
1a910 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
1a920 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20  ()] API enables 
1a930 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68  or disables both
1a940 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73   the.** C-API [s
1a950 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
1a960 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65  nsion()] and the
1a970 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c   SQL function [l
1a980 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d  oad_extension()]
1a990 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
1a9a0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
1a9b0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
1a9c0 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74  * When the first
1a9d0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
1a9e0 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 31  s interface is 1
1a9f0 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20  , then only the 
1aa00 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62  C-API is.** enab
1aa10 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20  led and the SQL 
1aa20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73  function remains
1aa30 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74   disabled.  If t
1aa40 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1aa50 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74  t to.** this int
1aa60 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 68 65  erface is 0, the
1aa70 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49  n both the C-API
1aa80 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e   and the SQL fun
1aa90 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c  ction are disabl
1aaa0 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69  ed..** If the fi
1aab0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
1aac0 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e  -1, then no chan
1aad0 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20  ges are made to 
1aae0 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 72 20  state of either 
1aaf0 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20  the.** C-API or 
1ab00 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
1ab10 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  ..** The second 
1ab20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
1ab30 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
1ab40 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
1ab50 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
1ab60 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
1ab70 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65   whether [sqlite
1ab80 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
1ab90 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
1aba0 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20   is disabled or 
1abb0 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e  enabled followin
1abc0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
1abd0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1abe0 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e  er may.** be a N
1abf0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20  ULL pointer, in 
1ac00 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 6e  which case the n
1ac10 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  ew setting is no
1ac20 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
1ac30 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
1ac40 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
1ac50 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f  FIG_MAINDBNAME</
1ac60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
1ac70 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
1ac80 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e   to change the n
1ac90 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e  ame of the "main
1aca0 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63  " database.** sc
1acb0 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65  hema.  ^The sole
1acc0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
1acd0 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73  ointer to a cons
1ace0 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67  tant UTF8 string
1acf0 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  .** which will b
1ad00 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63  ecome the new sc
1ad10 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61  hema name in pla
1ad20 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e  ce of "main".  ^
1ad30 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e  SQLite.** does n
1ad40 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f  ot make a copy o
1ad50 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73  f the new main s
1ad60 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e  chema name strin
1ad70 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63  g, so the applic
1ad80 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e  ation.** must en
1ad90 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61 72  sure that the ar
1ada0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e  gument passed in
1adb0 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47  to this DBCONFIG
1adc0 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61   option is uncha
1add0 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66  nged.** until af
1ade0 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73 65  ter the database
1adf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
1ae00 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  es..** </dd>.**.
1ae10 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
1ae20 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1ae30 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 20 20  FIG_MAINDBNAME  
1ae40 20 20 20 20 20 20 20 20 20 20 31 30 30 30 20 2f            1000 /
1ae50 2a 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 2a 2f  * const char* */
1ae60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ae70 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
1ae80 44 45 20 20 20 20 20 20 20 20 20 20 20 20 20 31  DE             1
1ae90 30 30 31 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  001 /* void* int
1aea0 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
1aeb0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1aec0 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
1aed0 20 20 20 20 20 20 31 30 30 32 20 2f 2a 20 69 6e        1002 /* in
1aee0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
1aef0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
1af00 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
1af10 20 20 20 20 20 20 20 20 31 30 30 33 20 2f 2a 20          1003 /* 
1af20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
1af30 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
1af40 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f  FIG_ENABLE_FTS3_
1af50 54 4f 4b 45 4e 49 5a 45 52 20 31 30 30 34 20 2f  TOKENIZER 1004 /
1af60 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64  * int int* */.#d
1af70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
1af80 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 4c 4f 41  ONFIG_ENABLE_LOA
1af90 44 5f 45 58 54 45 4e 53 49 4f 4e 20 31 30 30 35  D_EXTENSION 1005
1afa0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
1afb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1afc0 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
1afd0 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
1afe0 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d 45 54  ult Codes.** MET
1aff0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1b000 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b010 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
1b020 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
1b030 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
1b040 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
1b050 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
1b060 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
1b070 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
1b080 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
1b090 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
1b0a0 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
1b0b0 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
1b0c0 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c  tibility..*/.SQL
1b0d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1b0e0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
1b0f0 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
1b100 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
1b110 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b120 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
1b130 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  id.** METHOD: sq
1b140 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  lite3.**.** ^Eac
1b150 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20  h entry in most 
1b160 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65  SQLite tables (e
1b170 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f  xcept for [WITHO
1b180 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
1b190 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75  ).** has a uniqu
1b1a0 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
1b1b0 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
1b1c0 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
1b1d0 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
1b1e0 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
1b1f0 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
1b200 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
1b210 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
1b220 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
1b230 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
1b240 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
1b250 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
1b260 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
1b270 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
1b280 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
1b290 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
1b2a0 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
1b2b0 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
1b2c0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
1b2d0 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
1b2e0 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
1b2f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1b300 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
1b310 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63  owid(D) interfac
1b320 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
1b330 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a  owid] of the .**
1b340 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
1b350 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
1b360 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61   into a rowid ta
1b370 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ble or [virtual 
1b380 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74  table].** on dat
1b390 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b3a0 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20   D..** ^Inserts 
1b3b0 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f  into [WITHOUT RO
1b3c0 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20  WID] tables are 
1b3d0 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a  not recorded..**
1b3e0 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
1b3f0 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74  ul [INSERT]s int
1b400 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a  o rowid tables.*
1b410 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
1b420 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61  rred on the data
1b430 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1b440 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  D, .** then sqli
1b450 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1b460 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
1b470 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49   zero..**.** ^(I
1b480 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
1b490 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
1b4a0 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
1b4b0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
1b4c0 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
1b4d0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
1b4e0 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
1b4f0 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
1b500 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
1b510 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
1b520 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
1b530 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
1b540 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
1b550 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
1b560 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
1b570 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
1b580 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1b590 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
1b5a0 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
1b5b0 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
1b5c0 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
1b5d0 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
1b5e0 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
1b5f0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
1b600 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
1b610 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
1b620 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
1b630 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
1b640 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
1b650 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
1b660 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
1b670 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
1b680 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
1b690 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
1b6a0 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
1b6b0 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
1b6c0 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
1b6d0 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
1b6e0 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
1b6f0 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
1b700 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
1b710 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
1b720 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
1b730 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
1b740 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
1b750 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
1b760 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
1b770 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
1b780 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
1b790 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
1b7a0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
1b7b0 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
1b7c0 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
1b7d0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
1b7e0 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
1b7f0 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
1b800 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
1b810 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1b820 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
1b830 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
1b840 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
1b850 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
1b860 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
1b870 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
1b880 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
1b890 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
1b8a0 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
1b8b0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
1b8c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
1b8d0 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
1b8e0 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
1b8f0 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
1b900 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
1b910 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
1b920 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
1b930 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
1b940 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
1b950 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
1b960 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
1b970 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
1b980 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1b990 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
1b9a0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
1b9b0 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
1b9c0 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
1b9d0 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
1b9e0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1b9f0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
1ba00 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1ba10 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
1ba20 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
1ba30 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
1ba40 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
1ba50 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
1ba60 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
1ba70 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1ba80 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1ba90 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1baa0 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
1bab0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
1bac0 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
1bad0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
1bae0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1baf0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1bb00 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1bb10 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
1bb20 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e  ows modified, in
1bb30 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  serted or.** del
1bb40 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
1bb50 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
1bb60 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
1bb70 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  TE or DELETE.** 
1bb80 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65  statement on the
1bb90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1bba0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62  tion specified b
1bbb0 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  y the only param
1bbc0 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74  eter..** ^Execut
1bbd0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
1bbe0 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
1bbf0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64  ent does not mod
1bc00 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  ify the value.**
1bc10 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
1bc20 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
1bc30 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  * ^Only changes 
1bc40 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79  made directly by
1bc50 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44   the INSERT, UPD
1bc60 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1bc70 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63  atement are.** c
1bc80 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69  onsidered - auxi
1bc90 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
1bca0 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20  used by [CREATE 
1bcb0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
1bcc0 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67  rs], .** [foreig
1bcd0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f  n key actions] o
1bce0 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  r [REPLACE] cons
1bcf0 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
1bd00 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  n are not counte
1bd10 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65  d..** .** Change
1bd20 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
1bd30 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
1bd40 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44   by .** [INSTEAD
1bd50 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e   OF trigger | IN
1bd60 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1bd70 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
1bd80 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a  ed. ^The value .
1bd90 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
1bda0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1bdb0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
1bdc0 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  er an INSERT, UP
1bdd0 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45  DATE or .** DELE
1bde0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e  TE statement run
1bdf0 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c   on a view is al
1be00 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20  ways zero. Only 
1be10 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20  changes made to 
1be20 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20  real .** tables 
1be30 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
1be40 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f  ** Things are mo
1be50 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69  re complicated i
1be60 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  f the sqlite3_ch
1be70 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
1be80 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   is.** executed 
1be90 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20  while a trigger 
1bea0 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69  program is runni
1beb0 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70  ng. This may hap
1bec0 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72  pen if the.** pr
1bed0 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b  ogram uses the [
1bee0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1bef0 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73  nction], or if s
1bf00 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61  ome other callba
1bf10 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ck.** function i
1bf20 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63  nvokes sqlite3_c
1bf30 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c  hanges() directl
1bf40 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a  y. Essentially:.
1bf50 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  ** .** <ul>.**  
1bf60 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65   <li> ^(Before e
1bf70 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65  ntering a trigge
1bf80 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61  r program the va
1bf90 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a  lue returned by.
1bfa0 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65  **        sqlite
1bfb0 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
1bfc0 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41  tion is saved. A
1bfd0 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72  fter the trigger
1bfe0 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20   program .**    
1bff0 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64      has finished
1c000 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76  , the original v
1c010 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64  alue is restored
1c020 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69  .)^.** .**   <li
1c030 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69  > ^(Within a tri
1c040 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63  gger program eac
1c050 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  h INSERT, UPDATE
1c060 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20   and DELETE .** 
1c070 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
1c080 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20   sets the value 
1c090 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1c0a0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
1c0b0 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f  *        upon co
1c0c0 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d  mpletion as norm
1c0d0 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74  al. Of course, t
1c0e0 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e  his value will n
1c0f0 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20  ot include .**  
1c100 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65        any change
1c110 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73  s performed by s
1c120 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20  ub-triggers, as 
1c130 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
1c140 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
1c150 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73   value will be s
1c160 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65  aved and restore
1c170 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62  d after each sub
1c180 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e  -trigger has run
1c190 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  .)^.** </ul>.** 
1c1a0 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20  .** ^This means 
1c1b0 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e  that if the chan
1c1c0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1c1d0 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20  on (or similar) 
1c1e0 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  is used.** by th
1c1f0 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20  e first INSERT, 
1c200 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1c210 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1c220 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20  n a trigger, it 
1c230 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
1c240 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65  value as set whe
1c250 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74  n the calling st
1c260 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78  atement began ex
1c270 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20  ecuting..** ^If 
1c280 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68  it is used by th
1c290 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73  e second or subs
1c2a0 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74  equent such stat
1c2b0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74  ement within a t
1c2c0 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72  rigger .** progr
1c2d0 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  am, the value re
1c2e0 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20  turned reflects 
1c2f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1c300 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74  ws modified by t
1c310 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  he .** previous 
1c320 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1c330 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
1c340 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
1c350 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a  me trigger..**.*
1c360 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
1c370 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1c380 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1c390 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
1c3a0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
1c3b0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e  ], and the [chan
1c3c0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1c3d0 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
1c3e0 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1c3f0 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
1c400 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
1c410 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1c420 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1c430 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
1c440 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
1c450 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1c460 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
1c470 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
1c480 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  gful..*/.SQLITE_
1c490 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1c4a0 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
1c4b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c4c0 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72  EF: Total Number
1c4d0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
1c4e0 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  d.** METHOD: sql
1c4f0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1c500 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1c510 73 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62  s the total numb
1c520 65 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72  er of rows inser
1c530 74 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72  ted, modified or
1c540 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61  .** deleted by a
1c550 6c 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  ll [INSERT], [UP
1c560 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
1c570 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d  ] statements com
1c580 70 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20  pleted.** since 
1c590 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1c5a0 6e 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e  nection was open
1c5b0 65 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  ed, including th
1c5c0 6f 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a  ose executed as.
1c5d0 2a 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67  ** part of trigg
1c5e0 65 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78  er programs. ^Ex
1c5f0 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65  ecuting any othe
1c600 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74  r type of SQL st
1c610 61 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20  atement.** does 
1c620 6e 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76  not affect the v
1c630 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
1c640 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1c650 68 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a  hanges()..** .**
1c660 20 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61   ^Changes made a
1c670 73 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69  s part of [forei
1c680 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20  gn key actions] 
1c690 61 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  are included in 
1c6a0 74 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75  the.** count, bu
1c6b0 74 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20  t those made as 
1c6c0 70 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20  part of REPLACE 
1c6d0 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
1c6e0 75 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74  ution are.** not
1c6f0 2e 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20  . ^Changes to a 
1c700 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e  view that are in
1c710 74 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53  tercepted by INS
1c720 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73  TEAD OF triggers
1c730 20 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75   .** are not cou
1c740 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65  nted..** .** See
1c750 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
1c760 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
1c770 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
1c780 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
1c790 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
1c7a0 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
1c7b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
1c7c0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1c7d0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
1c7e0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
1c7f0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
1c800 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
1c810 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1c820 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
1c830 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
1c840 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
1c850 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
1c860 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
1c870 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ngful..*/.SQLITE
1c880 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1c890 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
1c8a0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1c8b0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
1c8c0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
1c8d0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
1c8e0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1c8f0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1c900 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
1c910 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
1c920 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
1c930 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
1c940 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
1c950 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
1c960 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
1c970 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
1c980 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
1c990 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
1c9a0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
1c9b0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
1c9c0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
1c9d0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
1c9e0 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
1c9f0 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
1ca00 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
1ca10 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
1ca20 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
1ca30 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
1ca40 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
1ca50 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
1ca60 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
1ca70 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
1ca80 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
1ca90 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
1caa0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1cab0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
1cac0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cad0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
1cae0 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
1caf0 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
1cb00 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1cb10 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1cb20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
1cb30 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
1cb40 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
1cb50 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
1cb60 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1cb70 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
1cb80 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
1cb90 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
1cba0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
1cbb0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
1cbc0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
1cbd0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
1cbe0 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
1cbf0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
1cc00 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
1cc10 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
1cc20 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
1cc30 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
1cc40 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1cc50 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1cc60 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
1cc70 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
1cc80 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
1cc90 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
1cca0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
1ccb0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
1ccc0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
1ccd0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
1cce0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
1ccf0 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
1cd00 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
1cd10 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
1cd20 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1cd30 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
1cd40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cd50 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
1cd60 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
1cd70 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1cd80 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1cd90 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1cda0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1cdb0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
1cdc0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
1cdd0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
1cde0 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
1cdf0 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
1ce00 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
1ce10 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
1ce20 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1ce30 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
1ce40 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1ce50 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1ce60 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
1ce70 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
1ce80 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
1ce90 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
1cea0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
1ceb0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
1cec0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
1ced0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1cee0 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
1cef0 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
1cf00 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
1cf10 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
1cf20 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
1cf30 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
1cf40 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1cf50 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1cf60 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1cf70 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1cf80 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
1cf90 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1cfa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
1cfb0 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
1cfc0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
1cfd0 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
1cfe0 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
1cff0 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
1d000 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1d010 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
1d020 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
1d030 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d040 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
1d050 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1d060 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
1d070 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1d080 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
1d090 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
1d0a0 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
1d0b0 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
1d0c0 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
1d0d0 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
1d0e0 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
1d0f0 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
1d100 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
1d110 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
1d120 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
1d130 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
1d140 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
1d150 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
1d160 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
1d170 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1d180 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
1d190 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
1d1a0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
1d1b0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
1d1c0 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
1d1d0 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
1d1e0 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
1d1f0 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
1d200 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
1d210 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
1d220 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
1d230 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
1d240 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
1d250 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
1d260 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
1d270 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
1d280 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
1d290 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
1d2a0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
1d2b0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
1d2c0 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
1d2d0 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
1d2e0 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
1d2f0 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
1d300 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
1d310 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
1d320 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
1d330 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
1d340 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
1d350 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
1d360 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
1d370 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1d380 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
1d390 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1d3a0 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
1d3b0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
1d3c0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
1d3d0 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
1d3e0 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
1d3f0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1d400 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
1d410 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
1d420 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
1d430 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
1d440 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
1d450 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
1d460 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
1d470 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
1d480 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
1d490 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1d4a0 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
1d4b0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
1d4c0 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
1d4d0 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
1d4e0 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
1d4f0 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
1d500 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
1d510 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
1d520 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
1d530 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
1d540 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1d550 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
1d560 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
1d570 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
1d580 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
1d590 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1d5a0 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
1d5b0 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
1d5c0 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1d5d0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1d5e0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1d5f0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1d600 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
1d610 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1d620 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1d630 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
1d640 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1d650 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1d660 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
1d670 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c  te order..*/.SQL
1d680 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1d690 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
1d6a0 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53  st char *sql);.S
1d6b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1d6c0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1d6d0 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
1d6e0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d6f0 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
1d700 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
1d710 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
1d720 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  rors.** KEYWORDS
1d730 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20  : {busy-handler 
1d740 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20  callback} {busy 
1d750 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48  handler}.** METH
1d760 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1d770 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
1d780 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c  usy_handler(D,X,
1d790 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  P) routine sets 
1d7a0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
1d7b0 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69  ion X.** that mi
1d7c0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
1d7d0 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77  ith argument P w
1d7e0 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
1d7f0 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
1d800 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61   access a databa
1d810 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61  se table associa
1d820 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74  ted with.** [dat
1d830 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d840 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72  ] D when another
1d850 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72   thread.** or pr
1d860 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61  ocess has the ta
1d870 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54  ble locked..** T
1d880 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  he sqlite3_busy_
1d890 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66  handler() interf
1d8a0 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69  ace is used to i
1d8b0 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c  mplement.** [sql
1d8c0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
1d8d0 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41  t()] and [PRAGMA
1d8e0 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a   busy_timeout]..
1d8f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75  **.** ^If the bu
1d900 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1d910 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54  ULL, then [SQLIT
1d920 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65  E_BUSY].** is re
1d930 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
1d940 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65  ly upon encounte
1d950 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20  ring the lock.  
1d960 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c  ^If the busy cal
1d970 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20  lback.** is not 
1d980 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63  NULL, then the c
1d990 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65  allback might be
1d9a0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77   invoked with tw
1d9b0 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a  o arguments..**.
1d9c0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
1d9d0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75  gument to the bu
1d9e0 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20  sy handler is a 
1d9f0 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64  copy of the void
1da00 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a  * pointer which.
1da10 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20  ** is the third 
1da20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1da30 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1da40 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64  ().  ^The second
1da50 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
1da60 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1da70 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1da80 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73   number of times
1da90 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68   that the busy h
1daa0 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65  andler has.** be
1dab0 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69  en invoked previ
1dac0 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61  ously for the sa
1dad0 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  me locking event
1dae0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
1daf0 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
1db00 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
1db10 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
1db20 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
1db30 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
1db40 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
1db50 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72  E_BUSY] is retur
1db60 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  ned.** to the ap
1db70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  plication..** ^I
1db80 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
1db90 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1dba0 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
1dbb0 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
1dbc0 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
1dbd0 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20  atabase and the 
1dbe0 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
1dbf0 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
1dc00 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
1dc10 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
1dc20 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
1dc30 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
1dc40 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
1dc50 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
1dc60 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
1dc70 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
1dc80 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
1dc90 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
1dca0 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
1dcb0 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
1dcc0 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
1dcd0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
1dce0 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1dcf0 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20  tion instead of 
1dd00 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a  invoking the .**
1dd10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1dd20 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
1dd30 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
1dd40 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1dd50 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
1dd60 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
1dd70 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
1dd80 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
1dd90 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
1dda0 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
1ddb0 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
1ddc0 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
1ddd0 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
1dde0 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
1ddf0 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
1de00 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
1de10 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
1de20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1de30 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
1de40 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
1de50 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
1de60 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
1de70 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1de80 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
1de90 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
1dea0 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
1deb0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
1dec0 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
1ded0 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
1dee0 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
1def0 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
1df00 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
1df10 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1df20 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
1df30 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
1df40 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
1df50 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
1df60 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
1df70 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
1df80 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
1df90 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
1dfa0 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
1dfb0 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1dfc0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ULL..**.** ^(The
1dfd0 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1dfe0 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1dff0 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
1e000 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
1e010 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
1e020 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
1e030 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
1e040 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
1e050 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
1e060 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
1e070 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
1e080 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
1e090 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  .** or evaluatin
1e0a0 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  g [PRAGMA busy_t
1e0b0 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63  imeout=N] will c
1e0c0 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73  hange the.** bus
1e0d0 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68  y handler and th
1e0e0 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65  us clear any pre
1e0f0 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79  viously set busy
1e100 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
1e110 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
1e120 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
1e130 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
1e140 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
1e150 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1e160 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
1e170 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1e180 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ler.  In other w
1e190 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73  ords,.** the bus
1e1a0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74  y handler is not
1e1b0 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79   reentrant.  Any
1e1c0 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
1e1d0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
1e1e0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
1e1f0 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
1e200 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
1e210 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
1e220 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
1e230 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
1e240 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
1e250 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1e260 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  dler..*/.SQLITE_
1e270 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1e280 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c  busy_handler(sql
1e290 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f 69  ite3*,int(*)(voi
1e2a0 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b 0a  d*,int),void*);.
1e2b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e2c0 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
1e2d0 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  out.** METHOD: s
1e2e0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1e2f0 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
1e300 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
1e310 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
1e320 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
1e330 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
1e340 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
1e350 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
1e360 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
1e370 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
1e380 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
1e390 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
1e3a0 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1e3b0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1e3c0 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
1e3d0 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
1e3e0 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
1e3f0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1e400 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
1e410 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
1e420 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
1e430 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e440 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
1e450 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
1e460 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69  .** ^Calling thi
1e470 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61  s routine with a
1e480 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20  n argument less 
1e490 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f  than or equal to
1e4a0 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f   zero.** turns o
1e4b0 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64  ff all busy hand
1e4c0 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lers..**.** ^(Th
1e4d0 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1e4e0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1e4f0 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74  ndler for a part
1e500 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62  icular.** [datab
1e510 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1e520 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  at any given mom
1e530 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
1e540 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
1e550 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
1e560 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
1e570 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
1e580 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
1e590 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
1e5a0 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
1e5b0 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
1e5c0 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  red.)^.**.** See
1e5d0 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20   also:  [PRAGMA 
1e5e0 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f  busy_timeout].*/
1e5f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1e600 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
1e610 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  eout(sqlite3*, i
1e620 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  nt ms);../*.** C
1e630 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69  API3REF: Conveni
1e640 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f  ence Routines Fo
1e650 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65  r Running Querie
1e660 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
1e670 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ite3.**.** This 
1e680 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65  is a legacy inte
1e690 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72  rface that is pr
1e6a0 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b  eserved for back
1e6b0 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
1e6c0 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74  ity..** Use of t
1e6d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73  his interface is
1e6e0 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64   not recommended
1e6f0 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69  ..**.** Definiti
1e700 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20  on: A <b>result 
1e710 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d  table</b> is mem
1e720 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75  ory data structu
1e730 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68  re created by th
1e740 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65  e.** [sqlite3_ge
1e750 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72  t_table()] inter
1e760 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20  face.  A result 
1e770 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68  table records th
1e780 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75  e.** complete qu
1e790 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d  ery results from
1e7a0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65   one or more que
1e7b0 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ries..**.** The 
1e7c0 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c  table conceptual
1e7d0 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20  ly has a number 
1e7e0 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75  of rows and colu
1e7f0 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65  mns.  But.** the
1e800 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e  se numbers are n
1e810 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72  ot part of the r
1e820 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65  esult table itse
1e830 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75  lf.  These.** nu
1e840 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e  mbers are obtain
1e850 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20  ed separately.  
1e860 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d  Let N be the num
1e870 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61  ber of rows.** a
1e880 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62  nd M be the numb
1e890 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a  er of columns..*
1e8a0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1e8b0 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20  ble is an array 
1e8c0 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a  of pointers to z
1e8d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1e8e0 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  TF-8 strings..**
1e8f0 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29   There are (N+1)
1e900 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74  *M elements in t
1e910 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66  he array.  The f
1e920 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20  irst M pointers 
1e930 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f  point.** to zero
1e940 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1e950 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69  ngs that  contai
1e960 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74  n the names of t
1e970 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54  he columns..** T
1e980 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74  he remaining ent
1e990 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74  ries all point t
1e9a0 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e  o query results.
1e9b0 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65    NULL values re
1e9c0 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20  sult.** in NULL 
1e9d0 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f  pointers.  All o
1e9e0 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20  ther values are 
1e9f0 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a  in their UTF-8 z
1ea00 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1ea10 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65  * string represe
1ea20 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72  ntation as retur
1ea30 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
1ea40 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a  column_text()]..
1ea50 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1ea60 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69  able might consi
1ea70 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  st of one or mor
1ea80 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
1ea90 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e  ions..** It is n
1eaa0 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20  ot safe to pass 
1eab0 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64  a result table d
1eac0 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69  irectly to [sqli
1ead0 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20  te3_free()]..** 
1eae0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73  A result table s
1eaf0 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63  hould be dealloc
1eb00 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
1eb10 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1eb20 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e  ]..**.** ^(As an
1eb30 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20   example of the 
1eb40 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72  result table for
1eb50 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71  mat, suppose a q
1eb60 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69  uery result.** i
1eb70 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1eb80 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1eb90 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
1eba0 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67  Name        | Ag
1ebb0 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d  e.**        ----
1ebc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1ebd0 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c  ---.**        Al
1ebe0 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a  ice       | 43.*
1ebf0 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20  *        Bob    
1ec00 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20       | 28.**    
1ec10 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20      Cindy       
1ec20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  | 21.** </pre></
1ec30 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1ec40 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20  * There are two 
1ec50 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e  column (M==2) an
1ec60 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d  d three rows (N=
1ec70 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a  =3).  Thus the.*
1ec80 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68  * result table h
1ec90 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53  as 8 entries.  S
1eca0 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c  uppose the resul
1ecb0 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65  t table is store
1ecc0 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79  d.** in an array
1ecd0 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e   names azResult.
1ece0 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20    Then azResult 
1ecf0 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65  holds this conte
1ed00 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  nt:.**.** <block
1ed10 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1ed20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1ed30 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a  91;0] = "Name";.
1ed40 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1ed50 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65  lt&#91;1] = "Age
1ed60 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1ed70 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22  esult&#91;2] = "
1ed80 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20  Alice";.**      
1ed90 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33    azResult&#91;3
1eda0 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20  ] = "43";.**    
1edb0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1edc0 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20  ;4] = "Bob";.** 
1edd0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1ede0 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a  #91;5] = "28";.*
1edf0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1ee00 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64  t&#91;6] = "Cind
1ee10 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  y";.**        az
1ee20 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20  Result&#91;7] = 
1ee30 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  "21";.** </pre><
1ee40 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a  /blockquote>)^.*
1ee50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1ee60 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75  3_get_table() fu
1ee70 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73  nction evaluates
1ee80 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
1ee90 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61  semicolon-separa
1eea0 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
1eeb0 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74  ts in the zero-t
1eec0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a  erminated UTF-8.
1eed0 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73  ** string of its
1eee0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
1eef0 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73  nd returns a res
1ef00 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65  ult table to the
1ef10 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65  .** pointer give
1ef20 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72  n in its 3rd par
1ef30 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66  ameter..**.** Af
1ef40 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  ter the applicat
1ef50 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64  ion has finished
1ef60 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74   with the result
1ef70 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65   from sqlite3_ge
1ef80 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74  t_table(),.** it
1ef90 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72   must pass the r
1efa0 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e  esult table poin
1efb0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66  ter to sqlite3_f
1efc0 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f  ree_table() in o
1efd0 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61  rder to.** relea
1efe0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68  se the memory th
1eff0 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e  at was malloced.
1f000 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65    Because of the
1f010 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   way the.** [sql
1f020 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68  ite3_malloc()] h
1f030 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71  appens within sq
1f040 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1f050 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a  ), the calling.*
1f060 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
1f070 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20  not try to call 
1f080 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1f090 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79   directly.  Only
1f0a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1f0b0 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62  e_table()] is ab
1f0c0 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68  le to release th
1f0d0 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c  e memory properl
1f0e0 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a  y and safely..**
1f0f0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1f100 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65  get_table() inte
1f110 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65  rface is impleme
1f120 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65  nted as a wrappe
1f130 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
1f140 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54  ite3_exec()].  T
1f150 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1f160 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64  able() routine d
1f170 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63  oes not have acc
1f180 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e  ess.** to any in
1f190 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75  ternal data stru
1f1a0 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65  ctures of SQLite
1f1b0 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20  .  It uses only 
1f1c0 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e  the public.** in
1f1d0 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20  terface defined 
1f1e0 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73  here.  As a cons
1f1f0 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20  equence, errors 
1f200 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68  that occur in th
1f210 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79  e.** wrapper lay
1f220 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  er outside of th
1f230 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69  e internal [sqli
1f240 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c  te3_exec()] call
1f250 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c   are not.** refl
1f260 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75  ected in subsequ
1f270 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
1f280 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
1f290 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
1f2a0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51  errmsg()]..*/.SQ
1f2b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1f2c0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a  ite3_get_table(.
1f2d0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1f2e0 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70          /* An op
1f2f0 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  en database */. 
1f300 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
1f310 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f  l,     /* SQL to
1f320 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
1f330 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65  .  char ***pazRe
1f340 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75  sult,    /* Resu
1f350 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79  lts of the query
1f360 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77   */.  int *pnRow
1f370 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e  ,           /* N
1f380 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
1f390 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72  rows written her
1f3a0 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f  e */.  int *pnCo
1f3b0 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20  lumn,        /* 
1f3c0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1f3d0 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e   columns written
1f3e0 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20   here */.  char 
1f3f0 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20  **pzErrmsg      
1f400 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
1f410 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
1f420 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1f430 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
1f440 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c  ble(char **resul
1f450 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1f460 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53  REF: Formatted S
1f470 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46  tring Printing F
1f480 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54  unctions.**.** T
1f490 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1f4a0 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66  e work-alikes of
1f4b0 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22 20   the "printf()" 
1f4c0 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69  family of functi
1f4d0 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ons.** from the 
1f4e0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
1f4f0 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ry..** These rou
1f500 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e 64  tines understand
1f510 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f 6d   most of the com
1f520 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74 69  mon K&R formatti
1f530 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20 70  ng options,.** p
1f540 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69 6f  lus some additio
1f550 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72 64  nal non-standard
1f560 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69 6c   formats, detail
1f570 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f 74  ed below..** Not
1f580 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20 74  e that some of t
1f590 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65 20  he more obscure 
1f5a0 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f  formatting optio
1f5b0 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a 2a  ns from recent.*
1f5c0 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61 6e  * C-library stan
1f5d0 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74 65  dards are omitte
1f5e0 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70 6c  d from this impl
1f5f0 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  ementation..**.*
1f600 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1f610 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
1f620 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
1f630 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
1f640 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
1f650 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
1f660 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
1f670 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
1f680 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1f690 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
1f6a0 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
1f6b0 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
1f6c0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
1f6d0 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
1f6e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
1f6f0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
1f700 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
1f710 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
1f720 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
1f730 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
1f740 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
1f750 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
1f760 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
1f770 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1f780 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
1f790 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
1f7a0 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
1f7b0 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
1f7c0 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
1f7d0 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
1f7e0 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
1f7f0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1f800 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
1f810 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
1f820 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
1f830 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
1f840 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
1f850 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
1f860 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
1f870 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
1f880 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
1f890 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
1f8a0 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
1f8b0 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
1f8c0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1f8d0 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
1f8e0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
1f8f0 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
1f900 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1f910 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
1f920 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
1f930 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
1f940 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
1f950 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
1f960 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
1f970 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
1f980 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
1f990 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1f9a0 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
1f9b0 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
1f9c0 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
1f9d0 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
1f9e0 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
1f9f0 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
1fa00 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1fa10 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
1fa20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1fa30 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1fa40 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
1fa50 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
1fa60 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
1fa70 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
1fa80 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
1fa90 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
1faa0 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
1fab0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
1fac0 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
1fad0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
1fae0 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
1faf0 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
1fb00 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
1fb10 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
1fb20 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
1fb30 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
1fb40 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
1fb50 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
1fb60 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
1fb70 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
1fb80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1fb90 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
1fba0 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
1fbb0 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
1fbc0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1fbd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
1fbe0 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
1fbf0 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
1fc00 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
1fc10 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
1fc20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
1fc30 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
1fc40 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
1fc50 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
1fc60 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
1fc70 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
1fc80 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
1fc90 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
1fca0 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25 77   "%q", "%Q", "%w
1fcb0 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f  " and "%z" optio
1fcc0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ns..**.** ^(The 
1fcd0 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %q option works 
1fce0 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20  like %s in that 
1fcf0 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61  it substitutes a
1fd00 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a   nul-terminated.
1fd10 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
1fd20 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
1fd30 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
1fd40 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
1fd50 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
1fd60 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
1fd70 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
1fd80 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
1fd90 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
1fda0 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
1fdb0 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
1fdc0 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
1fdd0 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
1fde0 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
1fdf0 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
1fe00 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
1fe10 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
1fe20 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
1fe30 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
1fe40 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
1fe50 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1fe60 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1fe70 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
1fe80 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
1fe90 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1fea0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
1feb0 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
1fec0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1fed0 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
1fee0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1fef0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1ff00 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1ff10 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1ff20 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1ff30 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
1ff40 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1ff50 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1ff60 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1ff70 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1ff80 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1ff90 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
1ffa0 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
1ffb0 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
1ffc0 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
1ffd0 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
1ffe0 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
1fff0 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
20000 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
20010 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
20020 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
20030 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
20040 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
20050 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
20060 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
20070 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
20080 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
20090 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
200a0 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
200b0 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
200c0 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
200d0 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
200e0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
200f0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
20100 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
20110 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
20120 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
20130 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
20140 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
20150 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
20160 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
20170 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
20180 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
20190 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
201a0 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
201b0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
201c0 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
201d0 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
201e0 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
201f0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
20200 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
20210 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
20220 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
20230 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
20240 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
20250 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
20260 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
20270 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
20280 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
20290 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
202a0 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
202b0 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
202c0 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
202d0 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
202e0 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
202f0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
20300 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
20310 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
20320 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
20330 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
20340 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
20350 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
20360 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
20370 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
20380 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
20390 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
203a0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
203b0 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
203c0 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
203d0 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
203e0 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
203f0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
20400 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
20410 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
20420 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
20430 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74  (The "%w" format
20440 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 6c  ting option is l
20450 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74 20  ike "%q" except 
20460 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73 20  that it expects 
20470 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69 6e  to.** be contain
20480 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c 65  ed within double
20490 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64 20  -quotes instead 
204a0 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  of single quotes
204b0 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63 61  , and it.** esca
204c0 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d 71  pes the double-q
204d0 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20 69  uote character i
204e0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73 69  nstead of the si
204f0 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63 68  ngle-quote.** ch
20500 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65 20  aracter.)^  The 
20510 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%w" formatting 
20520 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e 64  option is intend
20530 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69 6e  ed for safely in
20540 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c 65  serting.** table
20550 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   and column name
20560 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72 75  s into a constru
20570 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  cted SQL stateme
20580 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  nt..**.** ^(The 
20590 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
205a0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
205b0 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20  e "%s" but with 
205c0 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
205d0 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
205e0 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
205f0 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
20600 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
20610 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
20620 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
20630 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
20640 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  g.)^.*/.SQLITE_A
20650 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
20660 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
20670 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54  har*,...);.SQLIT
20680 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
20690 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
206a0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
206b0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
206c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
206d0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
206e0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
206f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
20700 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
20710 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
20720 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
20730 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
20740 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
20750 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
20760 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
20770 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
20780 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
20790 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
207a0 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
207b0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
207c0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
207d0 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
207e0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
207f0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
20800 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
20810 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
20820 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
20830 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
20840 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
20850 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
20860 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
20870 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
20880 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
20890 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
208a0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
208b0 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
208c0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
208d0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
208e0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
208f0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
20900 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
20910 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
20920 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
20930 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
20940 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
20950 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
20960 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
20970 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
20980 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
20990 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
209a0 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
209b0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
209c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
209d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
209e0 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f 75  _malloc64(N) rou
209f0 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74 20  tine works just 
20a00 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  like.** sqlite3_
20a10 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70 74  malloc(N) except
20a20 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75 6e   that N is an un
20a30 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69 6e  signed 64-bit in
20a40 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a  teger instead.**
20a50 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32 2d   of a signed 32-
20a60 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a  bit integer..**.
20a70 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
20a80 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20  te3_free() with 
20a90 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f  a pointer previo
20aa0 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a  usly returned.**
20ab0 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
20ac0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
20ad0 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73  realloc() releas
20ae0 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73  es that memory s
20af0 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67  o.** that it mig
20b00 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e  ht be reused.  ^
20b10 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65  The sqlite3_free
20b20 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a  () routine is.**
20b30 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63   a no-op if is c
20b40 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
20b50 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73  L pointer.  Pass
20b60 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ing a NULL point
20b70 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  er.** to sqlite3
20b80 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c  _free() is harml
20b90 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e  ess.  After bein
20ba0 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a  g freed, memory.
20bb0 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65  ** should neithe
20bc0 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72  r be read nor wr
20bd0 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61  itten.  Even rea
20be0 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20  ding previously 
20bf0 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20  freed.** memory 
20c00 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20  might result in 
20c10 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66  a segmentation f
20c20 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65  ault or other se
20c30 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d  vere error..** M
20c40 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e  emory corruption
20c50 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  , a segmentation
20c60 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72   fault, or other
20c70 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a   severe error.**
20c80 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66   might result if
20c90 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
20ca0 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
20cb0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
20cc0 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f  r that.** was no
20cd0 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
20ce0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20cf0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   or sqlite3_real
20d00 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  loc()..**.** ^Th
20d10 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
20d20 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  c(X,N) interface
20d30 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
20d40 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
20d50 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
20d60 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73   X to be at leas
20d70 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49  t N bytes..** ^I
20d80 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74 65  f the X paramete
20d90 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
20da0 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73 20  lloc(X,N).** is 
20db0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
20dc0 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
20dd0 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
20de0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
20df0 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a 2a  te3_malloc(N)..*
20e00 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72 61  * ^If the N para
20e10 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
20e20 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 73  _realloc(X,N) is
20e30 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
20e40 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
20e50 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
20e60 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
20e70 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
20e80 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73 71  _free(X)..** ^sq
20e90 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
20ea0 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  N) returns a poi
20eb0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
20ec0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
20ed0 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
20ee0 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
20ef0 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65  LL if insufficie
20f00 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61  nt memory is ava
20f10 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
20f20 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
20f30 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
20f40 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
20f50 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
20f60 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
20f70 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
20f80 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
20f90 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
20fa0 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
20fb0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
20fc0 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
20fd0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
20fe0 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
20ff0 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20  e3_realloc(X,N) 
21000 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
21010 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c 20   N is positive, 
21020 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69 6f  then the.** prio
21030 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
21040 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
21050 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
21060 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e 74  alloc64(X,N) int
21070 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74 68  erfaces works th
21080 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71 6c  e same as.** sql
21090 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
210a0 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20  ) except that N 
210b0 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73 69  is a 64-bit unsi
210c0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e 73  gned integer ins
210d0 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32 2d  tead.** of a 32-
210e0 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
210f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58 20  er..**.** ^If X 
21100 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  is a memory allo
21110 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73 6c  cation previousl
21120 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
21130 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
21140 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
21150 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65 33  loc64(), sqlite3
21160 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20 73  _realloc(), or s
21170 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34  qlite3_realloc64
21180 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  (), then.** sqli
21190 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74  te3_msize(X) ret
211a0 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f 66  urns the size of
211b0 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c 6c   that memory all
211c0 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65 73  ocation in bytes
211d0 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 20  ..** ^The value 
211e0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
211f0 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69 67  te3_msize(X) mig
21200 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68 61  ht be larger tha
21210 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a 20  n the number.** 
21220 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73 74  of bytes request
21230 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61 6c  ed when X was al
21240 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58 20  located.  ^If X 
21250 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
21260 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  r then.** sqlite
21270 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75 72  3_msize(X) retur
21280 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20 70  ns zero.  If X p
21290 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68 69  oints to somethi
212a0 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a 2a  ng that is not.*
212b0 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  * the beginning 
212c0 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  of memory alloca
212d0 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20 70  tion, or if it p
212e0 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d 65  oints to a forme
212f0 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65 6d  rly.** valid mem
21300 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
21310 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65 6e  hat has now been
21320 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68 65   freed, then the
21330 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20   behavior.** of 
21340 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58 29  sqlite3_msize(X)
21350 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
21360 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d 66  d possibly harmf
21370 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ul..**.** ^The m
21380 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
21390 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
213a0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
213b0 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  loc(),.** sqlite
213c0 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61 6e  3_malloc64(), an
213d0 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  d sqlite3_reallo
213e0 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  c64().** is alwa
213f0 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
21400 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
21410 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
21420 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
21430 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
21440 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
21450 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
21460 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
21470 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
21480 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
21490 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
214a0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
214b0 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
214c0 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
214d0 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
214e0 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
214f0 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
21500 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
21510 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
21520 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
21530 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
21540 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
21550 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
21560 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
21570 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
21580 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
21590 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
215a0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
215b0 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
215c0 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
215d0 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
215e0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
215f0 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
21600 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
21610 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
21620 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
21630 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
21640 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
21650 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
21660 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
21670 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
21680 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
21690 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
216a0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
216b0 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
216c0 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
216d0 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
216e0 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
216f0 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
21700 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
21710 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
21720 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
21730 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
21740 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
21750 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
21760 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
21770 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
21780 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
21790 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
217a0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
217b0 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
217c0 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
217d0 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
217e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
217f0 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
21800 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
21810 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
21820 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
21830 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
21840 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
21850 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
21860 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
21870 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
21880 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
21890 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
218a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
218b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
218c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
218d0 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  oc(int);.SQLITE_
218e0 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
218f0 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74  3_malloc64(sqlit
21900 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49  e3_uint64);.SQLI
21910 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
21920 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69  ite3_realloc(voi
21930 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
21940 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
21950 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69  e3_realloc64(voi
21960 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  d*, sqlite3_uint
21970 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
21980 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
21990 65 28 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  e(void*);.SQLITE
219a0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 75 69 6e  _API sqlite3_uin
219b0 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a  t64 sqlite3_msiz
219c0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
219d0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
219e0 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
219f0 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
21a00 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
21a10 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
21a20 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
21a30 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
21a40 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
21a50 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
21a60 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
21a70 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
21a80 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
21a90 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
21aa0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
21ab0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
21ac0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
21ad0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
21ae0 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
21af0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
21b00 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
21b10 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
21b20 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
21b30 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
21b40 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
21b50 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
21b60 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
21b70 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
21b80 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
21b90 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
21ba0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
21bb0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
21bc0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
21bd0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
21be0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
21bf0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
21c00 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
21c10 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
21c20 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
21c30 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
21c40 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
21c50 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
21c60 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
21c70 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
21c80 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
21c90 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
21ca0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
21cb0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
21cc0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
21cd0 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
21ce0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
21cf0 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
21d00 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
21d10 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
21d20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
21d30 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
21d40 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
21d50 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
21d60 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
21d70 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
21d80 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
21d90 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
21da0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
21db0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
21dc0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
21dd0 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
21de0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
21df0 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
21e00 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
21e10 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
21e20 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
21e30 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ed(void);.SQLITE
21e40 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
21e50 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
21e60 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
21e70 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
21e80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
21e90 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
21ea0 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
21eb0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
21ec0 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
21ed0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
21ee0 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
21ef0 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
21f00 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
21f10 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
21f20 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
21f30 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
21f40 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
21f50 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
21f60 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
21f70 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
21f80 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
21f90 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
21fa0 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
21fb0 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
21fc0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
21fd0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
21fe0 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
21ff0 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
22000 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
22010 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
22020 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
22030 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
22040 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
22050 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
22060 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20  to buffer P..** 
22070 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72  ^The P parameter
22080 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70   can be a NULL p
22090 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ointer..**.** ^I
220a0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68  f this routine h
220b0 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76  as not been prev
220c0 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72  iously called or
220d0 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   if the previous
220e0 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c  .** call had N l
220f0 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20  ess than one or 
22100 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
22110 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50  or P, then the P
22120 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64  RNG is.** seeded
22130 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73   using randomnes
22140 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
22150 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20  the xRandomness 
22160 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65  method of.** the
22170 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
22180 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  3_vfs] object..*
22190 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f  * ^If the previo
221a0 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  us call to this 
221b0 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e  routine had an N
221c0 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e   of 1 or more an
221d0 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20  d a.** non-NULL 
221e0 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64  P then the pseud
221f0 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
22200 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
22210 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
22220 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
22230 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
22240 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
22250 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49   method..*/.SQLI
22260 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
22270 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69  te3_randomness(i
22280 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a  nt N, void *P);.
22290 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
222a0 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75   Compile-Time Au
222b0 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c  thorization Call
222c0 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  backs.** METHOD:
222d0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
222e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
222f0 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
22300 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
22310 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
22320 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
22330 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
22340 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
22350 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
22360 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
22370 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
22380 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
22390 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
223a0 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
223b0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
223c0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
223d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
223e0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
223f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
22400 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
22410 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
22420 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
22430 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
22440 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
22450 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
22460 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
22470 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
22480 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
22490 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
224a0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
224b0 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
224c0 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
224d0 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
224e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
224f0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
22500 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
22510 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
22520 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
22530 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
22540 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
22550 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
22560 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
22570 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
22580 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
22590 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
225a0 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
225b0 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
225c0 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
225d0 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
225e0 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
225f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
22600 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
22610 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
22620 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
22630 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
22640 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
22650 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
22660 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22670 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
22680 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
22690 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
226a0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
226b0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
226c0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
226d0 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
226e0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
226f0 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
22700 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
22710 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
22720 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
22730 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
22740 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
22750 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
22760 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
22770 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
22780 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
22790 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
227a0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
227b0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
227c0 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
227d0 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
227e0 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
227f0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
22800 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
22810 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
22820 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
22830 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
22840 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
22850 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
22860 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
22870 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
22880 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
22890 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
228a0 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
228b0 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
228c0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
228d0 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
228e0 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
228f0 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
22900 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
22910 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
22920 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
22930 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
22940 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
22950 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
22960 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
22970 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
22980 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
22990 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
229a0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
229b0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
229c0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
229d0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
229e0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
229f0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
22a00 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
22a10 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
22a20 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
22a30 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
22a40 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
22a50 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
22a60 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
22a70 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
22a80 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
22a90 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
22aa0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
22ab0 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
22ac0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
22ad0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
22ae0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
22af0 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
22b00 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
22b10 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
22b20 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
22b30 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
22b40 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
22b50 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
22b60 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
22b70 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
22b80 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
22b90 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
22ba0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
22bb0 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
22bc0 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
22bd0 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
22be0 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
22bf0 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
22c00 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
22c10 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
22c20 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
22c30 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
22c40 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
22c50 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
22c60 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
22c70 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
22c80 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
22c90 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
22ca0 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
22cb0 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
22cc0 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
22cd0 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
22ce0 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
22cf0 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
22d00 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
22d10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
22d20 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
22d30 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
22d40 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
22d50 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
22d60 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
22d70 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
22d80 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
22d90 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
22da0 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
22db0 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
22dc0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
22dd0 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
22de0 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
22df0 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
22e00 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
22e10 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
22e20 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
22e30 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
22e40 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
22e50 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
22e60 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
22e70 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
22e80 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
22e90 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
22ea0 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
22eb0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
22ec0 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
22ed0 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
22ee0 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
22ef0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
22f00 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
22f10 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
22f20 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
22f30 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
22f40 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
22f50 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
22f60 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
22f70 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
22f80 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
22f90 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
22fa0 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
22fb0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
22fc0 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
22fd0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
22fe0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
22ff0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
23000 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
23010 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
23020 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
23030 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
23040 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
23050 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
23060 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
23070 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
23080 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
23090 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
230a0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
230b0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
230c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
230d0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
230e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
230f0 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
23100 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
23110 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
23120 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23130 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
23140 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
23150 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
23160 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
23170 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
23180 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
23190 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
231a0 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
231b0 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
231c0 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
231d0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
231e0 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
231f0 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
23200 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
23210 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
23220 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
23230 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
23240 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
23250 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
23260 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
23270 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
23280 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
23290 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
232a0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
232b0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
232c0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
232d0 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
232e0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
232f0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
23300 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
23310 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
23320 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
23330 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
23340 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
23350 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
23360 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
23370 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
23380 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
23390 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
233a0 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
233b0 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
233c0 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
233d0 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
233e0 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53  ema change..*/.S
233f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
23400 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
23410 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
23420 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
23430 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
23440 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
23450 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
23460 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
23470 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
23480 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23490 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
234a0 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
234b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
234c0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
234d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
234e0 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
234f0 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
23500 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
23510 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
23520 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
23530 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
23540 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
23550 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
23560 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
23570 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
23580 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
23590 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
235a0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
235b0 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
235c0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
235d0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
235e0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
235f0 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
23600 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f 6c   [conflict resol
23610 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20 72  ution mode].** r
23620 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68 65  eturned from the
23630 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
23640 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
23650 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
23660 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
23670 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
23680 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
23690 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
236a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
236b0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
236c0 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
236d0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
236e0 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
236f0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
23700 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
23710 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
23720 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
23730 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
23740 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
23750 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
23760 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
23770 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
23780 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
23790 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
237a0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
237b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
237c0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
237d0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
237e0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
237f0 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
23800 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
23810 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
23820 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
23830 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
23840 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
23850 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
23860 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
23870 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
23880 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
23890 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
238a0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
238b0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
238c0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
238d0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
238e0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
238f0 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
23900 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
23910 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
23920 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
23930 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
23940 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
23950 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
23960 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
23970 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
23980 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
23990 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
239a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
239b0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
239c0 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
239d0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
239e0 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
239f0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
23a00 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
23a10 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
23a20 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
23a30 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
23a40 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
23a50 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
23a60 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
23a70 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
23a80 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
23a90 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
23aa0 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
23ab0 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
23ac0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23ad0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
23ae0 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
23af0 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
23b00 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
23b10 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
23b20 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
23b30 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
23b40 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
23b50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
23b60 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
23b70 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
23b80 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
23b90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
23ba0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
23bb0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
23bc0 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
23bd0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
23be0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
23bf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
23c00 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
23c10 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
23c20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
23c30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
23c40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23c50 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
23c60 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
23c70 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
23c80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
23c90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
23ca0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
23cb0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
23cc0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
23cd0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
23ce0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23cf0 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
23d00 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
23d10 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
23d20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
23d30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
23d40 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
23d50 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
23d60 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
23d70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
23d80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
23d90 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
23da0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
23db0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
23dc0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
23dd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
23de0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
23df0 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
23e00 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
23e10 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
23e20 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
23e30 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
23e40 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
23e50 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
23e60 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
23e70 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
23e80 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
23e90 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
23ea0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
23eb0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
23ec0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
23ed0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
23ee0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
23ef0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
23f00 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
23f10 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
23f20 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
23f30 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
23f40 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
23f50 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
23f60 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
23f70 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
23f80 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
23f90 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
23fa0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
23fb0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
23fc0 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
23fd0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
23fe0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
23ff0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24000 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
24010 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
24020 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
24030 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
24040 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24050 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
24060 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
24070 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
24080 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24090 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
240a0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
240b0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
240c0 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
240d0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
240e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
240f0 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
24100 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
24110 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
24120 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
24130 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24140 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
24150 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
24160 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
24170 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
24180 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24190 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
241a0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
241b0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
241c0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
241d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
241e0 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
241f0 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
24200 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
24210 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
24220 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
24230 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
24240 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
24250 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
24260 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
24270 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
24280 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
24290 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
242a0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
242b0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
242c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
242d0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
242e0 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
242f0 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
24300 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
24310 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
24320 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
24330 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
24340 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
24350 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
24360 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
24370 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
24380 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
24390 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
243a0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
243b0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
243c0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
243d0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
243e0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
243f0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
24400 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
24410 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
24420 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
24430 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
24440 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
24450 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
24460 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
24470 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
24480 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
24490 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
244a0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
244b0 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
244c0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
244d0 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
244e0 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
244f0 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
24500 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
24510 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
24520 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
24530 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20 20  ITE_RECURSIVE   
24540 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f 2a           33   /*
24550 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
24560 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
24570 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
24580 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
24590 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
245a0 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ions.** METHOD: 
245b0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68  sqlite3.**.** Th
245c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
245d0 20 64 65 70 72 65 63 61 74 65 64 2e 20 55 73 65   deprecated. Use
245e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72   the [sqlite3_tr
245f0 61 63 65 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  ace_v2()] interf
24600 61 63 65 0a 2a 2a 20 69 6e 73 74 65 61 64 20 6f  ace.** instead o
24610 66 20 74 68 65 20 72 6f 75 74 69 6e 65 73 20 64  f the routines d
24620 65 73 63 72 69 62 65 64 20 68 65 72 65 2e 0a 2a  escribed here..*
24630 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
24640 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
24650 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
24660 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
24670 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
24680 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
24690 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
246a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
246b0 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
246c0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
246d0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
246e0 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
246f0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
24700 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
24710 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
24720 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
24730 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
24740 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
24750 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
24760 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
24770 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
24780 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
24790 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
247a0 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
247b0 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
247c0 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
247d0 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
247e0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
247f0 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
24800 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
24810 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
24820 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
24830 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
24840 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
24850 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
24860 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
24870 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
24880 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er.)^.**.** The 
24890 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
248a0 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
248b0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61  e-time option ca
248c0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d  n be used to lim
248d0 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68  it.** the length
248e0 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
248f0 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20  eter] expansion 
24900 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  in the output of
24910 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
24920 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
24930 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
24940 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
24950 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
24960 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
24970 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
24980 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
24990 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
249a0 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
249b0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
249c0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
249d0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
249e0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
249f0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
24a00 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
24a10 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
24a20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
24a30 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
24a40 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
24a50 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
24a60 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
24a70 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
24a80 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
24a90 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
24aa0 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
24ab0 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
24ac0 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
24ad0 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
24ae0 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
24af0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
24b00 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
24b10 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
24b20 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
24b30 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
24b40 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
24b50 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
24b60 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
24b70 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
24b80 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
24b90 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
24ba0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
24bb0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
24bc0 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
24bd0 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a  EPRECATED void *
24be0 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
24bf0 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28  lite3*,.   void(
24c00 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
24c10 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
24c20 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  d*);.SQLITE_API 
24c30 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
24c40 44 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  D void *sqlite3_
24c50 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a  profile(sqlite3*
24c60 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66  ,.   void(*xProf
24c70 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ile)(void*,const
24c80 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75   char*,sqlite3_u
24c90 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a  int64), void*);.
24ca0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
24cb0 20 53 51 4c 20 54 72 61 63 65 20 45 76 65 6e 74   SQL Trace Event
24cc0 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
24cd0 44 53 3a 20 53 51 4c 49 54 45 5f 54 52 41 43 45  DS: SQLITE_TRACE
24ce0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
24cf0 73 74 61 6e 74 73 20 69 64 65 6e 74 69 66 79 20  stants identify 
24d00 63 6c 61 73 73 65 73 20 6f 66 20 65 76 65 6e 74  classes of event
24d10 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6d 6f  s that can be mo
24d20 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73 69 6e 67  nitored.** using
24d30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 72   the [sqlite3_tr
24d40 61 63 65 5f 76 32 28 29 5d 20 74 72 61 63 69 6e  ace_v2()] tracin
24d50 67 20 6c 6f 67 69 63 2e 20 20 54 68 65 20 74 68  g logic.  The th
24d60 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ird argument.** 
24d70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  to [sqlite3_trac
24d80 65 5f 76 32 28 29 5d 20 69 73 20 61 6e 20 4f 52  e_v2()] is an OR
24d90 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  -ed combination 
24da0 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f  of one or more o
24db0 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
24dc0 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 20 20 5e  ng constants.  ^
24dd0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
24de0 6e 74 20 74 6f 20 74 68 65 20 74 72 61 63 65 20  nt to the trace 
24df0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6f  callback.** is o
24e00 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
24e10 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a  ing constants..*
24e20 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63 69 6e 67  *.** New tracing
24e30 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62   constants may b
24e40 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
24e50 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  e releases..**.*
24e60 2a 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62  * ^A trace callb
24e70 61 63 6b 20 68 61 73 20 66 6f 75 72 20 61 72 67  ack has four arg
24e80 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c 62 61 63  uments: xCallbac
24e90 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a 20 5e  k(T,C,P,X)..** ^
24ea0 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74 20 69  The T argument i
24eb0 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 69 6e 74  s one of the int
24ec0 65 67 65 72 20 74 79 70 65 20 63 6f 64 65 73 20  eger type codes 
24ed0 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68 65 20 43  above..** ^The C
24ee0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63   argument is a c
24ef0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
24f00 78 74 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  xt pointer passe
24f10 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
24f20 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
24f30 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65  o [sqlite3_trace
24f40 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 50  _v2()]..** The P
24f50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e 74 73   and X arguments
24f60 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20 77 68   are pointers wh
24f70 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64 65 70  ose meanings dep
24f80 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20  end on T..**.** 
24f90 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
24fa0 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d 20 3c 64  _TRACE_STMT]] <d
24fb0 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53  t>SQLITE_TRACE_S
24fc0 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TMT</dt>.** <dd>
24fd0 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
24fe0 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63 6b 20 69  _STMT callback i
24ff0 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61  s invoked when a
25000 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
25010 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20 62 65 67  ent.** first beg
25020 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20  ins running and 
25030 70 6f 73 73 69 62 6c 79 20 61 74 20 6f 74 68 65  possibly at othe
25040 72 20 74 69 6d 65 73 20 64 75 72 69 6e 67 20 74  r times during t
25050 68 65 0a 2a 2a 20 65 78 65 63 75 74 69 6f 6e 20  he.** execution 
25060 6f 66 20 74 68 65 20 70 72 65 70 61 72 65 64 20  of the prepared 
25070 73 74 61 74 65 6d 65 6e 74 2c 20 73 75 63 68 20  statement, such 
25080 61 73 20 61 74 20 74 68 65 20 73 74 61 72 74 20  as at the start 
25090 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72 69 67 67  of each.** trigg
250a0 65 72 20 73 75 62 70 72 6f 67 72 61 6d 2e 20 5e  er subprogram. ^
250b0 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
250c0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
250d0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
250e0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 65  statement]. ^The
250f0 20 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   X argument is a
25100 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
25110 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a 20 69 73  ring which.** is
25120 20 74 68 65 20 75 6e 65 78 70 61 6e 64 65 64 20   the unexpanded 
25130 53 51 4c 20 74 65 78 74 20 6f 66 20 74 68 65 20  SQL text of the 
25140 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25150 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20 63 6f 6d  nt or an SQL com
25160 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74 20 69 6e  ment .** that in
25170 64 69 63 61 74 65 73 20 74 68 65 20 69 6e 76 6f  dicates the invo
25180 63 61 74 69 6f 6e 20 6f 66 20 61 20 74 72 69 67  cation of a trig
25190 67 65 72 2e 20 20 5e 54 68 65 20 63 61 6c 6c 62  ger.  ^The callb
251a0 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75 74 65 0a  ack can compute.
251b0 2a 2a 20 74 68 65 20 73 61 6d 65 20 74 65 78 74  ** the same text
251c0 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
251d0 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 20 62   been returned b
251e0 79 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  y the legacy [sq
251f0 6c 69 74 65 33 5f 74 72 61 63 65 28 29 5d 0a 2a  lite3_trace()].*
25200 2a 20 69 6e 74 65 72 66 61 63 65 20 62 79 20 75  * interface by u
25210 73 69 6e 67 20 74 68 65 20 58 20 61 72 67 75 6d  sing the X argum
25220 65 6e 74 20 77 68 65 6e 20 58 20 62 65 67 69 6e  ent when X begin
25230 73 20 77 69 74 68 20 22 2d 2d 22 20 61 6e 64 20  s with "--" and 
25240 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b 73 71 6c  invoking.** [sql
25250 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
25260 6c 28 50 29 5d 20 6f 74 68 65 72 77 69 73 65 2e  l(P)] otherwise.
25270 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25280 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 5d 5d 20  TRACE_PROFILE]] 
25290 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45  <dt>SQLITE_TRACE
252a0 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e 0a 2a 2a  _PROFILE</dt>.**
252b0 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f   <dd>^An SQLITE_
252c0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61  TRACE_PROFILE ca
252d0 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64 65 73 20  llback provides 
252e0 61 70 70 72 6f 78 69 6d 61 74 65 6c 79 20 74 68  approximately th
252f0 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66 6f 72 6d  e same.** inform
25300 61 74 69 6f 6e 20 61 73 20 69 73 20 70 72 6f 76  ation as is prov
25310 69 64 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ided by the [sql
25320 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 5d 20  ite3_profile()] 
25330 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  callback..** ^Th
25340 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e P argument is 
25350 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
25360 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25370 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a  ment] and the.**
25380 20 58 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e   X argument poin
25390 74 73 20 74 6f 20 61 20 36 34 2d 62 69 74 20 69  ts to a 64-bit i
253a0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
253b0 74 68 65 20 65 73 74 69 6d 61 74 65 64 20 6f 66  the estimated of
253c0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
253d0 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20 74 68 61  f nanosecond tha
253e0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
253f0 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
25400 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65 20 53 51   run..** ^The SQ
25410 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49  LITE_TRACE_PROFI
25420 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  LE callback is i
25430 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20  nvoked when the 
25440 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
25450 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  es..**.** [[SQLI
25460 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d 5d 20 3c  TE_TRACE_ROW]] <
25470 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43 45 5f  dt>SQLITE_TRACE_
25480 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ROW</dt>.** <dd>
25490 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
254a0 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b 20 69 73  _ROW callback is
254b0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
254c0 72 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20  r a prepared.** 
254d0 73 74 61 74 65 6d 65 6e 74 20 67 65 6e 65 72 61  statement genera
254e0 74 65 73 20 61 20 73 69 6e 67 6c 65 20 72 6f 77  tes a single row
254f0 20 6f 66 20 72 65 73 75 6c 74 2e 20 20 0a 2a 2a   of result.  .**
25500 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74   ^The P argument
25510 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
25520 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
25530 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68  tatement] and th
25540 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20  e.** X argument 
25550 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  is unused..**.**
25560 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f   [[SQLITE_TRACE_
25570 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CLOSE]] <dt>SQLI
25580 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45 3c 2f  TE_TRACE_CLOSE</
25590 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
255a0 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
255b0 45 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  E callback is in
255c0 76 6f 6b 65 64 20 77 68 65 6e 20 61 20 64 61 74  voked when a dat
255d0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
255e0 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a 2a 20 5e  ion closes..** ^
255f0 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20 69  The P argument i
25600 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
25610 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
25620 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63 74 0a  nection] object.
25630 2a 2a 20 61 6e 64 20 74 68 65 20 58 20 61 72 67  ** and the X arg
25640 75 6d 65 6e 74 20 69 73 20 75 6e 75 73 65 64 2e  ument is unused.
25650 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
25660 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
25670 45 5f 53 54 4d 54 20 20 20 20 20 20 20 30 78 30  E_STMT       0x0
25680 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
25690 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 20  _TRACE_PROFILE  
256a0 20 20 30 78 30 32 0a 23 64 65 66 69 6e 65 20 53    0x02.#define S
256b0 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20  QLITE_TRACE_ROW 
256c0 20 20 20 20 20 20 20 30 78 30 34 0a 23 64 65 66         0x04.#def
256d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ine SQLITE_TRACE
256e0 5f 43 4c 4f 53 45 20 20 20 20 20 20 30 78 30 38  _CLOSE      0x08
256f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25700 3a 20 53 51 4c 20 54 72 61 63 65 20 48 6f 6f 6b  : SQL Trace Hook
25710 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
25720 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  te3.**.** ^The s
25730 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
25740 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,M,X,P) interfa
25750 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 74  ce registers a t
25760 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  race callback.**
25770 20 66 75 6e 63 74 69 6f 6e 20 58 20 61 67 61 69   function X agai
25780 6e 73 74 20 5b 64 61 74 61 62 61 73 65 20 63 6f  nst [database co
25790 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 75 73 69  nnection] D, usi
257a0 6e 67 20 70 72 6f 70 65 72 74 79 20 6d 61 73 6b  ng property mask
257b0 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e 74 65 78   M.** and contex
257c0 74 20 70 6f 69 6e 74 65 72 20 50 2e 20 20 5e 49  t pointer P.  ^I
257d0 66 20 74 68 65 20 58 20 63 61 6c 6c 62 61 63 6b  f the X callback
257e0 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f 72 20 69   is.** NULL or i
257f0 66 20 74 68 65 20 4d 20 6d 61 73 6b 20 69 73 20  f the M mask is 
25800 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 61 63 69  zero, then traci
25810 6e 67 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  ng is disabled. 
25820 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67 75 6d 65   The.** M argume
25830 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
25840 20 62 69 74 77 69 73 65 20 4f 52 2d 65 64 20 63   bitwise OR-ed c
25850 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a  ombination of.**
25860 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 5b 53   zero or more [S
25870 51 4c 49 54 45 5f 54 52 41 43 45 5d 20 63 6f 6e  QLITE_TRACE] con
25880 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45  stants..**.** ^E
25890 61 63 68 20 63 61 6c 6c 20 74 6f 20 65 69 74 68  ach call to eith
258a0 65 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  er sqlite3_trace
258b0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74 72  () or sqlite3_tr
258c0 61 63 65 5f 76 32 28 29 20 6f 76 65 72 72 69 64  ace_v2() overrid
258d0 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65 6c 73 29  es .** (cancels)
258e0 20 61 6e 79 20 70 72 69 6f 72 20 63 61 6c 6c 73   any prior calls
258f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 74 72 61 63   to sqlite3_trac
25900 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 74  e() or sqlite3_t
25910 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  race_v2()..**.**
25920 20 5e 54 68 65 20 58 20 63 61 6c 6c 62 61 63 6b   ^The X callback
25930 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
25940 65 76 65 72 20 61 6e 79 20 6f 66 20 74 68 65 20  ever any of the 
25950 65 76 65 6e 74 73 20 69 64 65 6e 74 69 66 69 65  events identifie
25960 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b 20 4d 20  d by .** mask M 
25970 6f 63 63 75 72 2e 20 20 5e 54 68 65 20 69 6e 74  occur.  ^The int
25980 65 67 65 72 20 72 65 74 75 72 6e 20 76 61 6c 75  eger return valu
25990 65 20 66 72 6f 6d 20 74 68 65 20 63 61 6c 6c 62  e from the callb
259a0 61 63 6b 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ack is currently
259b0 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20 74 68 6f  .** ignored, tho
259c0 75 67 68 20 74 68 69 73 20 6d 61 79 20 63 68 61  ugh this may cha
259d0 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 72 65  nge in future re
259e0 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c 62 61 63  leases.  Callbac
259f0 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  k.** implementat
25a00 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72 65 74 75  ions should retu
25a10 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e 73 75 72  rn zero to ensur
25a20 65 20 66 75 74 75 72 65 20 63 6f 6d 70 61 74 69  e future compati
25a30 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41  bility..**.** ^A
25a40 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20   trace callback 
25a50 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
25a60 66 6f 75 72 20 61 72 67 75 6d 65 6e 74 73 3a 20  four arguments: 
25a70 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c 50 2c 58  callback(T,C,P,X
25a80 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20 61 72 67  )..** ^The T arg
25a90 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20  ument is one of 
25aa0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43  the [SQLITE_TRAC
25ab0 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e 74 73 20  E].** constants 
25ac0 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 79 20  to indicate why 
25ad0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 77 61 73  the callback was
25ae0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68   invoked..** ^Th
25af0 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e C argument is 
25b00 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
25b10 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  ntext pointer..*
25b20 2a 20 54 68 65 20 50 20 61 6e 64 20 58 20 61 72  * The P and X ar
25b30 67 75 6d 65 6e 74 73 20 61 72 65 20 70 6f 69 6e  guments are poin
25b40 74 65 72 73 20 77 68 6f 73 65 20 6d 65 61 6e 69  ters whose meani
25b50 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e 20 54 2e  ngs depend on T.
25b60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25b70 65 33 5f 74 72 61 63 65 5f 76 32 28 29 20 69 6e  e3_trace_v2() in
25b80 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e  terface is inten
25b90 64 65 64 20 74 6f 20 72 65 70 6c 61 63 65 20 74  ded to replace t
25ba0 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
25bb0 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
25bc0 5f 74 72 61 63 65 28 29 5d 20 61 6e 64 20 5b 73  _trace()] and [s
25bd0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
25be0 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68 69 63 68  ], both of which
25bf0 0a 2a 2a 20 61 72 65 20 64 65 70 72 65 63 61 74  .** are deprecat
25c00 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
25c10 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  I int sqlite3_tr
25c20 61 63 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ace_v2(.  sqlite
25c30 33 2a 2c 0a 20 20 75 6e 73 69 67 6e 65 64 20 75  3*,.  unsigned u
25c40 4d 61 73 6b 2c 0a 20 20 69 6e 74 28 2a 78 43 61  Mask,.  int(*xCa
25c50 6c 6c 62 61 63 6b 29 28 75 6e 73 69 67 6e 65 64  llback)(unsigned
25c60 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 2c 76 6f 69  ,void*,void*,voi
25c70 64 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 43 74  d*),.  void *pCt
25c80 78 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x.);../*.** CAPI
25c90 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
25ca0 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
25cb0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
25cc0 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
25cd0 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
25ce0 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
25cf0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
25d00 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
25d10 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
25d20 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
25d30 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
25d40 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
25d50 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
25d60 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
25d70 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
25d80 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
25d90 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
25da0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
25db0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
25dc0 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
25dd0 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
25de0 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
25df0 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
25e00 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
25e10 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
25e20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
25e30 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
25e40 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
25e50 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
25e60 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
25e70 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70  eter N is the ap
25e80 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72  proximate number
25e90 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
25ea0 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
25eb0 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
25ec0 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
25ed0 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
25ee0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
25ef0 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20  he callback X.  
25f00 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
25f10 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20  an one then the 
25f20 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64  progress.** hand
25f30 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ler is disabled.
25f40 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
25f50 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
25f60 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
25f70 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
25f80 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
25f90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
25fa0 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
25fb0 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
25fc0 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
25fd0 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
25fe0 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
25ff0 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
26000 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
26010 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
26020 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
26030 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
26040 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
26050 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
26060 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
26070 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
26080 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
26090 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
260a0 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
260b0 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
260c0 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
260d0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
260e0 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
260f0 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
26100 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
26110 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
26120 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
26130 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
26140 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
26150 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
26160 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
26170 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
26180 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
26190 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
261a0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
261b0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
261c0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
261d0 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
261e0 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
261f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
26200 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
26210 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
26220 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
26230 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
26240 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  id sqlite3_progr
26250 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69  ess_handler(sqli
26260 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a  te3*, int, int(*
26270 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29  )(void*), void*)
26280 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
26290 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77  F: Opening A New
262a0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
262b0 74 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  tion.** CONSTRUC
262c0 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  TOR: sqlite3.**.
262d0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
262e0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
262f0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
26300 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
26310 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
26320 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
26330 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
26340 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
26350 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
26360 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
26370 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
26380 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
26390 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
263a0 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
263b0 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
263c0 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
263d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
263e0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
263f0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
26400 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
26410 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
26420 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
26430 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
26440 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
26450 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
26460 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
26470 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
26480 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
26490 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
264a0 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
264b0 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
264c0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
264d0 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
264e0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
264f0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
26500 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
26510 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
26520 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
26530 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
26540 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
26550 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
26560 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
26570 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
26580 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
26590 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
265a0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
265b0 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
265c0 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
265d0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
265e0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
265f0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
26600 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
26610 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
26620 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
26630 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77  fault encoding w
26640 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72  ill be UTF-8 for
26650 20 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74   databases creat
26660 65 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69  ed using.** sqli
26670 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
26680 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
26690 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65    ^The default e
266a0 6e 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61  ncoding for data
266b0 62 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  bases.** created
266c0 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f   using sqlite3_o
266d0 70 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20  pen16() will be 
266e0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
266f0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
26700 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f  .**.** Whether o
26710 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f  r not an error o
26720 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73  ccurs when it is
26730 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63   opened, resourc
26740 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  es.** associated
26750 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
26760 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
26770 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65  handle should be
26780 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20   released by.** 
26790 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
267a0 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20  qlite3_close()] 
267b0 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f  when it is no lo
267c0 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a  nger required..*
267d0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
267e0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72  _open_v2() inter
267f0 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20  face works like 
26800 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a  sqlite3_open().*
26810 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  * except that it
26820 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64   accepts two add
26830 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65  itional paramete
26840 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rs for additiona
26850 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65  l control.** ove
26860 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  r the new databa
26870 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  se connection.  
26880 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61  ^(The flags para
26890 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  meter to.** sqli
268a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61  te3_open_v2() ca
268b0 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a  n take one of.**
268c0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
268d0 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74  hree values, opt
268e0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
268f0 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53   with the .** [S
26900 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
26910 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  EX], [SQLITE_OPE
26920 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53  N_FULLMUTEX], [S
26930 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
26940 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c  DCACHE],.** [SQL
26950 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
26960 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b  CACHE], and/or [
26970 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
26980 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20   flags:)^.**.** 
26990 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  <dl>.** ^(<dt>[S
269a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
269b0 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NLY]</dt>.** <dd
269c0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
269d0 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d   opened in read-
269e0 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74  only mode.  If t
269f0 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73  he database does
26a00 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20   not.** already 
26a10 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20  exist, an error 
26a20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
26a30 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
26a40 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
26a50 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20  DWRITE]</dt>.** 
26a60 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65  <dd>The database
26a70 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
26a80 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69  eading and writi
26a90 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20  ng if possible, 
26aa0 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e  or reading.** on
26ab0 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69  ly if the file i
26ac0 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65  s write protecte
26ad0 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69  d by the operati
26ae0 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65  ng system.  In e
26af0 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68  ither.** case th
26b00 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20  e database must 
26b10 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f  already exist, o
26b20 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f  therwise an erro
26b30 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f  r is returned.</
26b40 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
26b50 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
26b60 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
26b70 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
26b80 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26b90 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
26ba0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
26bb0 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64  and writing, and
26bc0 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a   is created if.*
26bd0 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c  * it does not al
26be0 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69  ready exist. Thi
26bf0 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f  s is the behavio
26c00 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73  r that is always
26c10 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c   used for.** sql
26c20 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
26c30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
26c40 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
26c50 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33  >.**.** If the 3
26c60 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
26c70 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26c80 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
26c90 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69  the.** combinati
26ca0 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20  ons shown above 
26cb0 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69  optionally combi
26cc0 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a  ned with other.*
26cd0 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
26ce0 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45  EADONLY | SQLITE
26cf0 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a  _OPEN_* bits].**
26d00 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
26d10 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
26d20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
26d30 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
26d40 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
26d50 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
26d60 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
26d70 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
26d80 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
26d90 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
26da0 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
26db0 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
26dc0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
26dd0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
26de0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
26df0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
26e00 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
26e10 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
26e20 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
26e30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
26e40 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
26e50 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
26e60 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
26e70 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
26e80 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
26e90 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
26ea0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
26eb0 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
26ec0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
26ed0 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
26ee0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
26ef0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
26f00 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
26f10 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
26f20 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
26f30 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
26f40 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
26f50 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
26f60 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
26f70 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
26f80 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
26f90 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
26fa0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
26fb0 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
26fc0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
26fd0 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
26fe0 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
26ff0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
27000 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
27010 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
27020 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
27030 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
27040 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
27050 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
27060 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
27070 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
27080 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
27090 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
270a0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
270b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
270c0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
270d0 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
270e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
270f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
27100 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
27110 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
27120 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
27130 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
27140 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
27150 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
27160 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
27170 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
27180 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
27190 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
271a0 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
271b0 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
271c0 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
271d0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
271e0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
271f0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
27200 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
27210 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
27220 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
27230 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
27240 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
27250 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
27260 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
27270 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
27280 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
27290 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
272a0 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
272b0 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
272c0 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
272d0 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
272e0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
272f0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
27300 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
27310 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
27320 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
27330 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
27340 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
27350 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
27360 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
27370 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
27380 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
27390 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
273a0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
273b0 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
273c0 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
273d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
273e0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  closed..**.** [[
273f0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e  URI filenames in
27400 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d   sqlite3_open()]
27410 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61  ] <h3>URI Filena
27420 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e  mes</h3>.**.** ^
27430 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  If [URI filename
27440 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  ] interpretation
27450 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64   is enabled, and
27460 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
27470 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73  gument.** begins
27480 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74   with "file:", t
27490 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  hen the filename
274a0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
274b0 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a  as a URI. ^URI.*
274c0 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  * filename inter
274d0 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
274e0 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c  bled if the [SQL
274f0 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
27500 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20  ag is.** set in 
27510 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
27520 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
27530 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
27540 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
27550 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
27560 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
27570 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
27580 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
27590 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
275a0 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79  ()] method or by
275b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45   the [SQLITE_USE
275c0 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  _URI] compile-ti
275d0 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73  me option..** As
275e0 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69   of SQLite versi
275f0 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69  on 3.7.7, URI fi
27600 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
27610 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ation is turned 
27620 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c  off.** by defaul
27630 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65  t, but future re
27640 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
27650 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52   might enable UR
27660 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e  I filename.** in
27670 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20  terpretation by 
27680 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b  default.  See "[
27690 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20  URI filenames]" 
276a0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
276b0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
276c0 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d  *.** URI filenam
276d0 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63  es are parsed ac
276e0 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33  cording to RFC 3
276f0 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49  986. ^If the URI
27700 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20   contains an.** 
27710 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20  authority, then 
27720 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  it must be eithe
27730 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  r an empty strin
27740 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20  g or the string 
27750 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e  .** "localhost".
27760 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
27770 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70  ty is not an emp
27780 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f  ty string or "lo
27790 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a  calhost", an .**
277a0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
277b0 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72  ed to the caller
277c0 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20  . ^The fragment 
277d0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
277e0 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65  RI, if .** prese
277f0 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  nt, is ignored..
27800 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
27810 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70  es the path comp
27820 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49  onent of the URI
27830 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   as the name of 
27840 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a  the disk file.**
27850 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20   which contains 
27860 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49  the database. ^I
27870 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e  f the path begin
27880 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61  s with a '/' cha
27890 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e  racter, .** then
278a0 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74   it is interpret
278b0 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74  ed as an absolut
278c0 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20  e path. ^If the 
278d0 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65  path does not be
278e0 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27  gin .** with a '
278f0 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74  /' (meaning that
27900 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73   the authority s
27910 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65  ection is omitte
27920 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a  d from the URI).
27930 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68  ** then the path
27940 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
27950 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61  as a relative pa
27960 74 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e  th. .** ^(On win
27970 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
27980 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
27990 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
279a0 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
279b0 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
279c0 20 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20   "C:").)^.**.** 
279d0 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79  [[core URI query
279e0 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a   parameters]].**
279f0 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   The query compo
27a00 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61  nent of a URI ma
27a10 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65  y contain parame
27a20 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e  ters that are in
27a30 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74  terpreted.** eit
27a40 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74  her by SQLite it
27a50 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56  self, or by a [V
27a60 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20  FS | custom VFS 
27a70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e  implementation].
27a80 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69  .** SQLite and i
27a90 74 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53  ts built-in [VFS
27aa0 65 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68  es] interpret th
27ab0 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71  e.** following q
27ac0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a  uery parameters:
27ad0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
27ae0 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e   <li> <b>vfs</b>
27af0 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72  : ^The "vfs" par
27b00 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73  ameter may be us
27b10 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ed to specify th
27b20 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20  e name of.**    
27b30 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68   a VFS object th
27b40 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20  at provides the 
27b50 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
27b60 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
27b70 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65  should.**     be
27b80 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20   used to access 
27b90 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27ba0 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74  e on disk. ^If t
27bb0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  his option is se
27bc0 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65  t to.**     an e
27bd0 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20  mpty string the 
27be0 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65  default VFS obje
27bf0 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65  ct is used. ^Spe
27c00 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
27c10 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73  wn.**     VFS is
27c20 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73   an error. ^If s
27c30 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27c40 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
27c50 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a   vfs option is.*
27c60 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74  *     present, t
27c70 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63  hen the VFS spec
27c80 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74  ified by the opt
27c90 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64  ion takes preced
27ca0 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20  ence over.**    
27cb0 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
27cc0 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20  d as the fourth 
27cd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
27ce0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
27cf0 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
27d00 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20  mode</b>: ^(The 
27d10 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d  mode parameter m
27d20 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74  ay be set to eit
27d30 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a  her "ro", "rw",.
27d40 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72  **     "rwc", or
27d50 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d   "memory". Attem
27d60 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
27d70 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c  to any other val
27d80 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20  ue is.**     an 
27d90 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20  error)^. .**    
27da0 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65   ^If "ro" is spe
27db0 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65  cified, then the
27dc0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
27dd0 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ned for read-onl
27de0 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  y .**     access
27df0 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65  , just as if the
27e00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
27e10 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64  ADONLY] flag had
27e20 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65   been set in the
27e30 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61   .**     third a
27e40 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
27e50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49  e3_open_v2(). ^I
27e60 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
27e70 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
27e80 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
27e90 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
27ea0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
27eb0 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
27ec0 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
27ed0 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
27ee0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
27ef0 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
27f00 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
27f10 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
27f20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
27f30 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
27f40 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
27f50 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
27f60 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
27f70 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
27f80 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
27f90 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
27fa0 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
27fb0 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
27fc0 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
27fd0 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
27fe0 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
27ff0 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
28000 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
28010 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
28020 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
28030 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
28040 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
28050 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
28060 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
28070 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
28080 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
28090 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
280a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
280b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
280c0 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
280d0 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
280e0 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
280f0 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
28100 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
28110 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
28120 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
28130 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
28140 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
28150 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
28160 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
28170 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
28180 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
28190 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
281a0 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
281b0 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
281c0 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
281d0 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
281e0 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
281f0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
28200 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
28210 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
28220 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
28230 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
28240 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
28250 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
28260 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
28270 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
28280 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
28290 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
282a0 65 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65  ehavior requeste
282b0 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20  d by setting.** 
282c0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
282d0 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20  PRIVATECACHE or 
282e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
282f0 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a  EDCACHE flag..**
28300 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f  .**  <li> <b>pso
28310 77 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77  w</b>: ^The psow
28320 20 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63   parameter indic
28330 61 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20  ates whether or 
28340 6e 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b  not the.**     [
28350 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72  powersafe overwr
28360 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f  ite] property do
28370 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61  es or does not a
28380 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20  pply to the.**  
28390 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61     storage media
283a0 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61   on which the da
283b0 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69  tabase file resi
283c0 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  des..**.**  <li>
283d0 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20   <b>nolock</b>: 
283e0 5e 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61  ^The nolock para
283f0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
28400 61 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  an query paramet
28410 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20  er.**     which 
28420 69 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20  if set disables 
28430 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20  file locking in 
28440 72 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c  rollback journal
28450 20 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a   modes.  This.**
28460 20 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66       is useful f
28470 6f 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64  or accessing a d
28480 61 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c  atabase on a fil
28490 65 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65  esystem that doe
284a0 73 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70  s not.**     sup
284b0 70 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43  port locking.  C
284c0 61 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73  aution:  Databas
284d0 65 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67  e corruption mig
284e0 68 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f  ht result if two
284f0 0a 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20  .**     or more 
28500 70 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20  processes write 
28510 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  to the same data
28520 62 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65  base and any one
28530 20 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20   of those.**    
28540 20 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20   processes uses 
28550 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20  nolock=1..**.** 
28560 20 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62   <li> <b>immutab
28570 6c 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d  le</b>: ^The imm
28580 75 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72  utable parameter
28590 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
285a0 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d  ery.**     param
285b0 65 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61  eter that indica
285c0 74 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74  tes that the dat
285d0 61 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74  abase file is st
285e0 6f 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72  ored on.**     r
285f0 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20  ead-only media. 
28600 20 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65   ^When immutable
28610 20 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20   is set, SQLite 
28620 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
28630 0a 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65  .**     database
28640 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
28650 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79  changed, even by
28660 20 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20   a process with 
28670 68 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72  higher.**     pr
28680 69 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20  ivilege, and so 
28690 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
286a0 6f 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79  opened read-only
286b0 20 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67   and all locking
286c0 0a 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e  .**     and chan
286d0 67 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20  ge detection is 
286e0 64 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69  disabled.  Cauti
286f0 6f 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20  on: Setting the 
28700 69 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20  immutable.**    
28710 20 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64   property on a d
28720 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61  atabase file tha
28730 74 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63  t does in fact c
28740 68 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74  hange can result
28750 0a 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72  .**     in incor
28760 72 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c  rect query resul
28770 74 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ts and/or [SQLIT
28780 45 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72  E_CORRUPT] error
28790 73 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c  s..**     See al
287a0 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  so: [SQLITE_IOCA
287b0 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a  P_IMMUTABLE]..**
287c0 20 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e         .** </ul>
287d0 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69  .**.** ^Specifyi
287e0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61  ng an unknown pa
287f0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71  rameter in the q
28800 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
28810 66 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61  f a URI is not a
28820 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74  n.** error.  Fut
28830 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
28840 53 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64  SQLite might und
28850 65 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e  erstand addition
28860 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61  al query.** para
28870 6d 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71  meters.  See "[q
28880 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20  uery parameters 
28890 77 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61  with special mea
288a0 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22  ning to SQLite]"
288b0 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   for.** addition
288c0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
288d0 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65  **.** [[URI file
288e0 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20  name examples]] 
288f0 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65  <h3>URI filename
28900 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a   examples</h3>.*
28910 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  *.** <table bord
28920 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e  er="1" align=cen
28930 74 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d  ter cellpadding=
28940 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55  5>.** <tr><th> U
28950 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68  RI filenames <th
28960 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72  > Results.** <tr
28970 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
28980 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
28990 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69       Open the fi
289a0 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20  le "data.db" in 
289b0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
289c0 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ctory..** <tr><t
289d0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
289e0 65 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a  ed/data.db<br>.*
289f0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
28a00 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ///home/fred/dat
28a10 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20  a.db <br> .**   
28a20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f         file://lo
28a30 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65  calhost/home/fre
28a40 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c  d/data.db <br> <
28a50 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
28a60 20 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   Open the databa
28a70 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  se file "/home/f
28a80 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a  red/data.db"..**
28a90 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
28aa0 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66  /darkstar/home/f
28ab0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e  red/data.db <td>
28ac0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
28ad0 20 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61   error. "darksta
28ae0 72 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f  r" is not a reco
28af0 67 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79  gnized authority
28b00 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79  ..** <tr><td sty
28b10 6c 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a  le="white-space:
28b20 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20  nowrap"> .**    
28b30 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a        file:///C:
28b40 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64  /Documents%20and
28b50 25 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64  %20Settings/fred
28b60 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62  /Desktop/data.db
28b70 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e  .**     <td> Win
28b80 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20  dows only: Open 
28b90 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
28ba0 62 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73  b" on fred's des
28bb0 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a  ktop on drive.**
28bc0 20 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f            C:. No
28bd0 74 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20  te that the %20 
28be0 65 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73  escaping in this
28bf0 20 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20   example is not 
28c00 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20  strictly .**    
28c10 20 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20        necessary 
28c20 2d 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65  - space characte
28c30 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c  rs can be used l
28c40 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20  iterally.**     
28c50 20 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65       in URI file
28c60 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  names..** <tr><t
28c70 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f  d> file:data.db?
28c80 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72  mode=ro&cache=pr
28c90 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20  ivate <td> .**  
28ca0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c          Open fil
28cb0 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
28cc0 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
28cd0 74 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e  tory for read-on
28ce0 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20  ly access..**   
28cf0 20 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73         Regardles
28d00 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
28d10 6e 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65  not shared-cache
28d20 20 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64   mode is enabled
28d30 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20   by.**          
28d40 64 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70  default, use a p
28d50 72 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a  rivate cache..**
28d60 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
28d70 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
28d80 62 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69  b?vfs=unix-dotfi
28d90 6c 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20  le <td>.**      
28da0 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f      Open file "/
28db0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
28dc0 62 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63  b". Use the spec
28dd0 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f  ial VFS "unix-do
28de0 74 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20  tfile".**       
28df0 20 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74     that uses dot
28e00 2d 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20  -files in place 
28e10 6f 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72  of posix advisor
28e20 79 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74  y locking..** <t
28e30 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
28e40 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c  .db?mode=readonl
28e50 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  y <td> .**      
28e60 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72      An error. "r
28e70 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20  eadonly" is not 
28e80 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66  a valid option f
28e90 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61  or the "mode" pa
28ea0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61  rameter..** </ta
28eb0 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20  ble>.**.** ^URI 
28ec0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
28ed0 70 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48  pe sequences (%H
28ee0 48 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64  H) are supported
28ef0 20 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68   within the path
28f00 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f   and.** query co
28f10 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52  mponents of a UR
28f20 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c  I. A hexadecimal
28f30 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
28f40 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a   consists of a.*
28f50 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d  * percent sign -
28f60 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20   "%" - followed 
28f70 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68  by exactly two h
28f80 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74  exadecimal digit
28f90 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67  s .** specifying
28fa0 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e   an octet value.
28fb0 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74   ^Before the pat
28fc0 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f  h or query compo
28fd0 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52  nents of a.** UR
28fe0 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69  I filename are i
28ff0 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79  nterpreted, they
29000 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69   are encoded usi
29010 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c  ng UTF-8 and all
29020 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c   .** hexadecimal
29030 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
29040 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  s replaced by a 
29050 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74  single byte cont
29060 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f  aining the.** co
29070 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65  rresponding octe
29080 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65  t. If this proce
29090 73 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20  ss generates an 
290a0 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e  invalid UTF-8 en
290b0 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72  coding,.** the r
290c0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
290d0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  ined..**.** <b>N
290e0 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75  ote to Windows u
290f0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65  sers:</b>  The e
29100 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72  ncoding used for
29110 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72   the filename ar
29120 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c  gument.** of sql
29130 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
29140 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
29150 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c  ) must be UTF-8,
29160 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a   not whatever.**
29170 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72   codepage is cur
29180 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20  rently defined. 
29190 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61   Filenames conta
291a0 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f  ining internatio
291b0 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  nal.** character
291c0 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  s must be conver
291d0 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69  ted to UTF-8 pri
291e0 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68  or to passing th
291f0 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74  em into.** sqlit
29200 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
29210 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
29220 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
29230 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65   Windows Runtime
29240 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
29250 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63   temporary direc
29260 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74  tory must be set
29270 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  .** prior to cal
29280 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65  ling sqlite3_ope
29290 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
292a0 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72  pen_v2().  Other
292b0 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a  wise, various.**
292c0 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72   features that r
292d0 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f  equire the use o
292e0 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  f temporary file
292f0 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a  s may fail..**.*
29300 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
29310 69 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74  ite3_temp_direct
29320 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ory].*/.SQLITE_A
29330 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
29340 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
29350 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
29360 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
29370 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
29380 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
29390 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
293a0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
293b0 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
293c0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
293d0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
293e0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
293f0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
29400 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
29410 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
29420 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
29430 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
29440 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  ndle */.);.SQLIT
29450 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
29460 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e  3_open_v2(.  con
29470 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
29480 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
29490 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
294a0 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
294b0 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f  *ppDb,         /
294c0 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
294d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74   handle */.  int
294e0 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20   flags,         
294f0 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f       /* Flags */
29500 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
29510 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61  Vfs        /* Na
29520 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65  me of VFS module
29530 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f   to use */.);../
29540 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
29550 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72  btain Values For
29560 20 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a   URI Parameters.
29570 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
29580 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73  utility routines
29590 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20  , useful to VFS 
295a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c  implementations,
295b0 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74   that check.** t
295c0 6f 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62  o see if a datab
295d0 61 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55  ase file was a U
295e0 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65  RI that containe
295f0 64 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65  d a specific que
29600 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ry .** parameter
29610 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61  , and if so obta
29620 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ins the value of
29630 20 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61   that query para
29640 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  meter..**.** If 
29650 46 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  F is the databas
29660 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74  e filename point
29670 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  er passed into t
29680 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f  he xOpen() metho
29690 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69  d of .** a VFS i
296a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
296b0 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72  en the flags par
296c0 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28  ameter to xOpen(
296d0 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a  ) has one or .**
296e0 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51   more of the [SQ
296f0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f  LITE_OPEN_URI] o
29700 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d  r [SQLITE_OPEN_M
29710 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74  AIN_DB] bits set
29720 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65   and.** P is the
29730 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65   name of the que
29740 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  ry parameter, th
29750 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  en.** sqlite3_ur
29760 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
29770 20 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c   returns the val
29780 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70  ue of the P.** p
29790 61 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65  arameter if it e
297a0 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20  xists or a NULL 
297b0 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65  pointer if P doe
297c0 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20  s not appear as 
297d0 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  a .** query para
297e0 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20  meter on F.  If 
297f0 50 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72  P is a query par
29800 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68  ameter of F.** h
29810 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76  as no explicit v
29820 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  alue, then sqlit
29830 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
29840 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a  (F,P) returns.**
29850 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
29860 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a   empty string..*
29870 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
29880 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
29890 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75  ,B) routine assu
298a0 6d 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20  mes that P is a 
298b0 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d  boolean.** param
298c0 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
298d0 20 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c   true (1) or fal
298e0 73 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67  se (0) according
298f0 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a   to the value.**
29900 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69   of P.  The sqli
29910 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
29920 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72  F,P,B) routine r
29930 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
29940 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20  if the.** value 
29950 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  of query paramet
29960 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
29970 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72  yes", "true", or
29980 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20   "on" in any.** 
29990 63 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76  case or if the v
299a0 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
299b0 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62   a non-zero numb
299c0 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c  er.  The .** sql
299d0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
299e0 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73  (F,P,B) routines
299f0 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28   returns false (
29a00 30 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  0) if the value 
29a10 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61  of.** query para
29a20 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
29a30 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c  f "no", "false",
29a40 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79   or "off" in any
29a50 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74   case or.** if t
29a60 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20  he value begins 
29a70 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a  with a numeric z
29a80 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f  ero.  If P is no
29a90 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72  t a query.** par
29aa0 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69  ameter on F or i
29ab0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
29ac0 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74   is does not mat
29ad0 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a  ch any of the.**
29ae0 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c   above, then sql
29af0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
29b00 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
29b10 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  (B!=0)..**.** Th
29b20 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  e sqlite3_uri_in
29b30 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69  t64(F,P,D) routi
29b40 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20  ne converts the 
29b50 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20  value of P into 
29b60 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e  a.** 64-bit sign
29b70 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72  ed integer and r
29b80 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65  eturns that inte
29b90 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64  ger, or D if P d
29ba0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74  oes not.** exist
29bb0 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20  .  If the value 
29bc0 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e  of P is somethin
29bd0 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20  g other than an 
29be0 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a  integer, then.**
29bf0 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
29c00 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69  d..** .** If F i
29c10 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
29c20 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
29c30 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
29c40 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61  ) returns NULL a
29c50 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  nd.** sqlite3_ur
29c60 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
29c70 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20   returns B.  If 
29c80 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20  F is not a NULL 
29c90 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69  pointer and.** i
29ca0 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65  s not a database
29cb0 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70   file pathname p
29cc0 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69  ointer that SQLi
29cd0 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74  te passed into t
29ce0 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20  he xOpen.** VFS 
29cf0 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65  method, then the
29d00 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69   behavior of thi
29d10 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64  s routine is und
29d20 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
29d30 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  bly.** undesirab
29d40 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  le..*/.SQLITE_AP
29d50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
29d60 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
29d70 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ter(const char *
29d80 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74  zFilename, const
29d90 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a   char *zParam);.
29da0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
29db0 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
29dc0 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
29dd0 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
29de0 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
29df0 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f  efault);.SQLITE_
29e00 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
29e10 34 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e  4 sqlite3_uri_in
29e20 74 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t64(const char*,
29e30 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71   const char*, sq
29e40 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a  lite3_int64);...
29e50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29e60 45 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20  Error Codes And 
29e70 4d 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48  Messages.** METH
29e80 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
29e90 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
29ea0 65 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20  ecent sqlite3_* 
29eb0 41 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61  API call associa
29ec0 74 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61  ted with .** [da
29ed0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
29ee0 6e 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65  n] D failed, the
29ef0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72  n the sqlite3_er
29f00 72 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61  rcode(D) interfa
29f10 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68  ce.** returns th
29f20 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
29f30 74 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65  t code] or [exte
29f40 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
29f50 5d 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50  ] for that.** AP
29f60 49 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68  I call..** If th
29f70 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  e most recent AP
29f80 49 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65  I call was succe
29f90 73 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74  ssful,.** then t
29fa0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
29fb0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72  from sqlite3_err
29fc0 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69  code() is undefi
29fd0 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ned..** ^The sql
29fe0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
29ff0 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72  rcode().** inter
2a000 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65  face is the same
2a010 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
2a020 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
2a030 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  he .** [extended
2a040 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76   result code] ev
2a050 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64  en when extended
2a060 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
2a070 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a  e.** disabled..*
2a080 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2a090 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
2a0a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
2a0b0 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
2a0c0 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
2a0d0 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
2a0e0 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
2a0f0 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
2a100 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65  TF-16 respective
2a110 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  ly..** ^(Memory 
2a120 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
2a130 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
2a140 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
2a150 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
2a160 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
2a170 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
2a180 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
2a190 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
2a1a0 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
2a1b0 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
2a1c0 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
2a1d0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
2a1e0 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
2a1f0 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
2a200 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
2a210 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a  nctions.)^.**.**
2a220 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
2a230 72 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65  rstr() interface
2a240 20 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67   returns the Eng
2a250 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65  lish-language te
2a260 78 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72  xt.** that descr
2a270 69 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74  ibes the [result
2a280 20 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38   code], as UTF-8
2a290 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
2a2a0 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
2a2b0 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
2a2c0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
2a2d0 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74  ally.** and must
2a2e0 20 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79   not be freed by
2a2f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2a300 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  )^..**.** When t
2a310 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
2a320 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
2a330 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
2a340 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
2a350 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
2a360 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
2a370 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
2a380 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
2a390 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
2a3a0 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
2a3b0 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
2a3c0 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
2a3d0 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
2a3e0 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
2a3f0 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
2a400 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
2a410 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
2a420 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
2a430 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
2a440 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
2a450 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
2a460 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
2a470 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
2a480 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2a490 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
2a4a0 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
2a4b0 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
2a4c0 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
2a4d0 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
2a4e0 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
2a4f0 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
2a500 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
2a510 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
2a520 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
2a530 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
2a540 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
2a550 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
2a560 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
2a570 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
2a580 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
2a590 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
2a5a0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
2a5b0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
2a5c0 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
2a5d0 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
2a5e0 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
2a5f0 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
2a600 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
2a610 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
2a620 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53  not be set..*/.S
2a630 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2a640 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
2a650 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
2a660 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2a670 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
2a680 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
2a690 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2a6a0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2a6b0 5f 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a  _errmsg(sqlite3*
2a6c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2a6d0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2a6e0 33 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74  3_errmsg16(sqlit
2a6f0 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  e3*);.SQLITE_API
2a700 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2a710 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
2a720 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a730 46 3a 20 50 72 65 70 61 72 65 64 20 53 74 61 74  F: Prepared Stat
2a740 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20  ement Object.** 
2a750 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61  KEYWORDS: {prepa
2a760 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b  red statement} {
2a770 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a780 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  nts}.**.** An in
2a790 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
2a7a0 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73  bject represents
2a7b0 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74   a single SQL st
2a7c0 61 74 65 6d 65 6e 74 20 74 68 61 74 0a 2a 2a 20  atement that.** 
2a7d0 68 61 73 20 62 65 65 6e 20 63 6f 6d 70 69 6c 65  has been compile
2a7e0 64 20 69 6e 74 6f 20 62 69 6e 61 72 79 20 66 6f  d into binary fo
2a7f0 72 6d 20 61 6e 64 20 69 73 20 72 65 61 64 79 20  rm and is ready 
2a800 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 2e  to be evaluated.
2a810 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b 20 6f 66 20  .**.** Think of 
2a820 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
2a830 6e 74 20 61 73 20 61 20 73 65 70 61 72 61 74 65  nt as a separate
2a840 20 63 6f 6d 70 75 74 65 72 20 70 72 6f 67 72 61   computer progra
2a850 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f 72 69 67 69  m.  The.** origi
2a860 6e 61 6c 20 53 51 4c 20 74 65 78 74 20 69 73 20  nal SQL text is 
2a870 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 41 20  source code.  A 
2a880 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a890 6e 74 20 6f 62 6a 65 63 74 20 0a 2a 2a 20 69 73  nt object .** is
2a8a0 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 6f 62   the compiled ob
2a8b0 6a 65 63 74 20 63 6f 64 65 2e 20 20 41 6c 6c 20  ject code.  All 
2a8c0 53 51 4c 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  SQL must be conv
2a8d0 65 72 74 65 64 20 69 6e 74 6f 20 61 0a 2a 2a 20  erted into a.** 
2a8e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a8f0 6e 74 20 62 65 66 6f 72 65 20 69 74 20 63 61 6e  nt before it can
2a900 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54   be run..**.** T
2a910 68 65 20 6c 69 66 65 2d 63 79 63 6c 65 20 6f 66  he life-cycle of
2a920 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2a930 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 75  ement object usu
2a940 61 6c 6c 79 20 67 6f 65 73 20 6c 69 6b 65 20 74  ally goes like t
2a950 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
2a960 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
2a970 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2a980 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 75 73 69  ement object usi
2a990 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
2a9a0 61 72 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 3c 6c  are_v2()]..** <l
2a9b0 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
2a9c0 6f 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 75  o [parameters] u
2a9d0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2a9e0 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
2a9f0 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
2aa00 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
2aa10 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
2aa20 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
2aa30 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
2aa40 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
2aa50 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
2aa60 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
2aa70 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68  ite3_reset()] th
2aa80 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20  en go back.**   
2aa90 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44     to step 2.  D
2aaa0 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d  o this zero or m
2aab0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
2aac0 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f  i> Destroy the o
2aad0 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c  bject using [sql
2aae0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2aaf0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79  ..** </ol>.*/.ty
2ab00 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2ab10 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
2ab20 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
2ab30 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
2ab40 65 20 4c 69 6d 69 74 73 0a 2a 2a 20 4d 45 54 48  e Limits.** METH
2ab50 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
2ab60 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
2ab70 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69  ce allows the si
2ab80 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f  ze of various co
2ab90 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c  nstructs to be l
2aba0 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63  imited.** on a c
2abb0 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e  onnection by con
2abc0 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20  nection basis.  
2abd0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2abe0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64  ter is the.** [d
2abf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ac00 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20  on] whose limit 
2ac10 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20  is to be set or 
2ac20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a  queried.  The.**
2ac30 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2ac40 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  r is one of the 
2ac50 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65  [limit categorie
2ac60 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  s] that define a
2ac70 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e  .** class of con
2ac80 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69  structs to be si
2ac90 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65  ze limited.  The
2aca0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2acb0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c   is the.** new l
2acc0 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f  imit for that co
2acd0 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a  nstruct.)^.**.**
2ace0 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d   ^If the new lim
2acf0 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65  it is a negative
2ad00 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d   number, the lim
2ad10 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e  it is unchanged.
2ad20 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c  .** ^(For each l
2ad30 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51  imit category SQ
2ad40 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41  LITE_LIMIT_<i>NA
2ad50 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20  ME</i> there is 
2ad60 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20  a .** [limits | 
2ad70 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
2ad80 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70  ].** set at comp
2ad90 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20  ile-time by a C 
2ada0 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
2adb0 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69  ro called.** [li
2adc0 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41  mits | SQLITE_MA
2add0 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a  X_<i>NAME</i>]..
2ade0 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f  ** (The "_LIMIT_
2adf0 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73  " in the name is
2ae00 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41   changed to "_MA
2ae10 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65  X_".))^.** ^Atte
2ae20 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65  mpts to increase
2ae30 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69   a limit above i
2ae40 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  ts hard upper bo
2ae50 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e  und are.** silen
2ae60 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f  tly truncated to
2ae70 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20   the hard upper 
2ae80 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65  bound..**.** ^Re
2ae90 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2aea0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c  her or not the l
2aeb0 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64  imit was changed
2aec0 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  , the .** [sqlit
2aed0 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65  e3_limit()] inte
2aee0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2aef0 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
2af00 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e   the limit..** ^
2af10 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74  Hence, to find t
2af20 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
2af30 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68   of a limit with
2af40 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c  out changing it,
2af50 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b  .** simply invok
2af60 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  e this interface
2af70 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20   with the third 
2af80 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f  parameter set to
2af90 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74   -1..**.** Run-t
2afa0 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69  ime limits are i
2afb0 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
2afc0 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  in applications 
2afd0 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62  that manage.** b
2afe0 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e  oth their own in
2aff0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20  ternal database 
2b000 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73  and also databas
2b010 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74  es that are cont
2b020 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74  rolled.** by unt
2b030 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20  rusted external 
2b040 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61  sources.  An exa
2b050 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  mple application
2b060 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77   might be a.** w
2b070 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20  eb browser that 
2b080 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61  has its own data
2b090 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e  bases for storin
2b0a0 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a  g history and.**
2b0b0 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61   separate databa
2b0c0 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62  ses controlled b
2b0d0 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70  y JavaScript app
2b0e0 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f  lications downlo
2b0f0 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20  aded.** off the 
2b100 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69  Internet.  The i
2b110 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
2b120 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74  s can be given t
2b130 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66  he.** large, def
2b140 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61  ault limits.  Da
2b150 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20  tabases managed 
2b160 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  by external sour
2b170 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69  ces can.** be gi
2b180 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72  ven much smaller
2b190 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64   limits designed
2b1a0 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65   to prevent a de
2b1b0 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a  nial of service.
2b1c0 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65  ** attack.  Deve
2b1d0 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73  lopers might als
2b1e0 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68  o want to use th
2b1f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
2b200 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20  uthorizer()].** 
2b210 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72  interface to fur
2b220 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74  ther control unt
2b230 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65  rusted SQL.  The
2b240 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74   size of the dat
2b250 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64  abase.** created
2b260 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64   by an untrusted
2b270 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63   script can be c
2b280 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74  ontained using t
2b290 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f  he.** [max_page_
2b2a0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e  count] [PRAGMA].
2b2b0 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74  .**.** New run-t
2b2c0 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f  ime limit catego
2b2d0 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  ries may be adde
2b2e0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
2b2f0 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ases..*/.SQLITE_
2b300 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2b310 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
2b320 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
2b330 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
2b340 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
2b350 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
2b360 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
2b370 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
2b380 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
2b390 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
2b3a0 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
2b3b0 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
2b3c0 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
2b3d0 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
2b3e0 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
2b3f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
2b400 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
2b410 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
2b420 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
2b430 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
2b440 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
2b450 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2b460 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
2b470 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
2b480 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
2b490 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
2b4a0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2b4b0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
2b4c0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2b4d0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2b4e0 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
2b4f0 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72  of any string or
2b500 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72   BLOB or table r
2b510 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64  ow, in bytes.<dd
2b520 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2b530 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
2b540 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
2b550 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
2b560 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
2b570 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
2b580 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61  th of an SQL sta
2b590 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73  tement, in bytes
2b5a0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2b5b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
2b5c0 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LUMN]] ^(<dt>SQL
2b5d0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
2b5e0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2b5f0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2b600 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
2b610 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e  table definition
2b620 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65   or in the.** re
2b630 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2b640 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61  ELECT] or the ma
2b650 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
2b660 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e  columns in an in
2b670 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20  dex.** or in an 
2b680 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55  ORDER BY or GROU
2b690 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64  P BY clause.</dd
2b6a0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2b6b0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
2b6c0 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
2b6d0 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
2b6e0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
2b6f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
2b700 68 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74  h of the parse t
2b710 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65  ree on any expre
2b720 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ssion.</dd>)^.**
2b730 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2b740 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
2b750 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  CT]] ^(<dt>SQLIT
2b760 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44  E_LIMIT_COMPOUND
2b770 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20  _SELECT</dt>.** 
2b780 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2b790 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  number of terms 
2b7a0 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45  in a compound SE
2b7b0 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c  LECT statement.<
2b7c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2b7d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
2b7e0 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  _OP]] ^(<dt>SQLI
2b7f0 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
2b800 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2b810 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2b820 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20  of instructions 
2b830 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63  in a virtual mac
2b840 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20  hine program.** 
2b850 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
2b860 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t an SQL stateme
2b870 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20  nt.  This limit 
2b880 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
2b890 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68  .** enforced, th
2b8a0 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20  ough that might 
2b8b0 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65  be added in some
2b8c0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
2b8d0 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64  of.** SQLite.</d
2b8e0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
2b8f0 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2b900 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53  ON_ARG]] ^(<dt>S
2b910 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2b920 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
2b930 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2b940 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
2b950 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
2b960 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
2b970 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
2b980 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74  ATTACHED]] ^(<dt
2b990 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
2b9a0 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
2b9b0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
2b9c0 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
2b9d0 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
2b9e0 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
2b9f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2ba00 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
2ba10 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c  _LENGTH]].** ^(<
2ba20 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
2ba30 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
2ba40 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GTH</dt>.** <dd>
2ba50 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67  The maximum leng
2ba60 74 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72  th of the patter
2ba70 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  n argument to th
2ba80 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b  e [LIKE] or.** [
2ba90 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e  GLOB] operators.
2baa0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
2bab0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2bac0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a  IABLE_NUMBER]].*
2bad0 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
2bae0 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
2baf0 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  MBER</dt>.** <dd
2bb00 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64  >The maximum ind
2bb10 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79  ex number of any
2bb20 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20   [parameter] in 
2bb30 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
2bb40 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  .)^.**.** [[SQLI
2bb50 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
2bb60 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
2bb70 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
2bb80 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  GER_DEPTH</dt>.*
2bb90 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
2bba0 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72  m depth of recur
2bbb0 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72  sion for trigger
2bbc0 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
2bbd0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57  [[SQLITE_LIMIT_W
2bbe0 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20  ORKER_THREADS]] 
2bbf0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2bc00 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44  IT_WORKER_THREAD
2bc10 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  S</dt>.** <dd>Th
2bc20 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
2bc30 20 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f   of auxiliary wo
2bc40 72 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61  rker threads tha
2bc50 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70  t a single.** [p
2bc60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2bc70 74 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64  t] may start.</d
2bc80 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
2bc90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2bca0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
2bcb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bcc0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
2bcd0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
2bce0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
2bcf0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
2bd00 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
2bd10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2bd20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2bd30 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
2bd40 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
2bd50 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
2bd60 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
2bd70 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
2bd80 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
2bd90 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
2bda0 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
2bdb0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
2bdc0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
2bdd0 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
2bde0 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
2bdf0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
2be00 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
2be10 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
2be20 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
2be30 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
2be40 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
2be50 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
2be60 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
2be70 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
2be80 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2be90 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
2bea0 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
2beb0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
2bec0 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20  _WORKER_THREADS 
2bed0 20 20 20 20 20 20 20 20 20 20 31 31 0a 0a 2f 2a            11../*
2bee0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2bef0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
2bf00 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
2bf10 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
2bf20 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
2bf30 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2bf40 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  3.** CONSTRUCTOR
2bf50 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2bf60 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
2bf70 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
2bf80 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
2bf90 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
2bfa0 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
2bfb0 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
2bfc0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2bfd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
2bfe0 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
2bff0 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
2c000 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
2c010 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
2c020 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
2c030 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2c040 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2c050 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
2c060 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2c070 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
2c080 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2c090 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
2c0a0 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
2c0b0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
2c0c0 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
2c0d0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
2c0e0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
2c0f0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
2c100 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
2c110 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
2c120 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
2c130 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2c140 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
2c150 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
2c160 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2c170 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
2c180 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2c190 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
2c1a0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
2c1b0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
2c1c0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2c1d0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
2c1e0 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
2c1f0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2c200 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f   ^If nByte is po
2c210 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  sitive, then it 
2c220 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2c230 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66   of bytes read f
2c240 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e  rom zSql.  ^If n
2c250 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68  Byte is zero, th
2c260 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a  en no prepared.*
2c270 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67  * statement is g
2c280 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20  enerated..** If 
2c290 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
2c2a0 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
2c2b0 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
2c2c0 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
2c2d0 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20  n.** there is a 
2c2e0 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63  small performanc
2c2f0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70  e advantage to p
2c300 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
2c310 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
2c320 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
2c330 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2c340 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
2c350 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
2c360 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
2c370 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  tor..**.** ^If p
2c380 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
2c390 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
2c3a0 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
2c3b0 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
2c3c0 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
2c3d0 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
2c3e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
2c3f0 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
2c400 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
2c410 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
2c420 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
2c430 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
2c440 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
2c450 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
2c460 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
2c470 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
2c480 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
2c490 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
2c4a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c4b0 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
2c4c0 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
2c4d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
2c4e0 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
2c4f0 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
2c500 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
2c510 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
2c520 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
2c530 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
2c540 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
2c550 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
2c560 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
2c570 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
2c580 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
2c590 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
2c5a0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
2c5b0 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
2c5c0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
2c5d0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
2c5e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2c5f0 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
2c600 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2c610 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
2c620 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
2c630 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
2c640 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
2c650 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
2c660 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
2c670 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
2c680 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
2c690 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2c6a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
2c6b0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2c6c0 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
2c6d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2c6e0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
2c6f0 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
2c700 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
2c710 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
2c720 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
2c730 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
2c740 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
2c750 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
2c760 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
2c770 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
2c780 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2c790 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
2c7a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2c7b0 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
2c7c0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2c7d0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
2c7e0 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
2c7f0 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
2c800 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
2c810 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
2c820 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
2c830 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
2c840 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
2c850 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
2c860 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
2c870 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
2c880 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
2c890 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
2c8a0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2c8b0 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
2c8c0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
2c8d0 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
2c8e0 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
2c8f0 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
2c900 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
2c910 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
2c920 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
2c930 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51  . As many as [SQ
2c940 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f  LITE_MAX_SCHEMA_
2c950 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65  RETRY].** retrie
2c960 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66  s will occur bef
2c970 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ore sqlite3_step
2c980 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20  () gives up and 
2c990 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72  returns an error
2c9a0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
2c9b0 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
2c9c0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
2c9d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2c9e0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
2c9f0 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
2ca00 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
2ca10 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
2ca20 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
2ca30 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2ca40 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
2ca50 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2ca60 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
2ca70 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
2ca80 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
2ca90 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
2caa0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
2cab0 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
2cac0 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
2cad0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2cae0 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
2caf0 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
2cb00 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
2cb10 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
2cb20 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
2cb30 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
2cb40 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
2cb50 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
2cb60 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
2cb70 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
2cb80 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
2cb90 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
2cba0 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
2cbb0 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
2cbc0 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
2cbd0 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
2cbe0 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
2cbf0 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
2cc00 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
2cc10 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
2cc20 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
2cc30 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2cc40 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
2cc50 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
2cc60 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
2cc70 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
2cc80 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
2cc90 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
2cca0 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
2ccb0 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
2ccc0 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
2ccd0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
2cce0 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
2ccf0 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
2cd00 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
2cd10 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
2cd20 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
2cd30 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
2cd40 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
2cd50 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
2cd60 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2cd70 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
2cd80 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
2cd90 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
2cda0 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
2cdb0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
2cdc0 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
2cdd0 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
2cde0 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
2cdf0 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
2ce00 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2ce10 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
2ce20 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
2ce30 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2ce40 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2ce50 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
2ce60 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2ce70 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2ce80 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2ce90 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2cea0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2ceb0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2cec0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2ced0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2cee0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2cef0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2cf00 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2cf10 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2cf20 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2cf30 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2cf40 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2cf50 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2cf60 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2cf70 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2cf80 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2cf90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2cfa0 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
2cfb0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2cfc0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2cfd0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2cfe0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2cff0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2d000 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2d010 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2d020 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2d030 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2d040 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2d050 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2d060 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2d070 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2d080 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2d090 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2d0a0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2d0b0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2d0c0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2d0d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2d0e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2d0f0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
2d100 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2d110 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2d120 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2d130 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2d140 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2d150 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2d160 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2d170 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2d180 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2d190 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2d1a0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2d1b0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2d1c0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2d1d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2d1e0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
2d1f0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2d200 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2d210 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2d220 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2d230 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2d240 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
2d250 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2d260 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2d270 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2d280 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2d290 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2d2a0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2d2b0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2d2c0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2d2d0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2d2e0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2d2f0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2d300 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2d310 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2d320 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2d330 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2d340 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2d350 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2d360 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2d370 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2d380 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
2d390 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
2d3a0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2d3b0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2d3c0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  The sqlite3_sql(
2d3d0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2d3e0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2d3f0 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  o a copy of the 
2d400 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78  UTF-8.** SQL tex
2d410 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
2d420 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d430 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73  ment] P if P was
2d440 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 65  .** created by e
2d450 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2d460 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2d470 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2d480 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68  16_v2()]..** ^Th
2d490 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  e sqlite3_expand
2d4a0 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  ed_sql(P) interf
2d4b0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2d4c0 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38  inter to a UTF-8
2d4d0 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
2d4e0 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65  ining the SQL te
2d4f0 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73  xt of prepared s
2d500 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a  tatement P with.
2d510 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  ** [bound parame
2d520 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a  ters] expanded..
2d530 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2d540 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72  ple, if a prepar
2d550 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2d560 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68  created using th
2d570 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53  e SQL.** text "S
2d580 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22  ELECT $abc,:xyz"
2d590 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65   and if paramete
2d5a0 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20  r $abc is bound 
2d5b0 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a  to integer 2345.
2d5c0 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72  ** and parameter
2d5d0 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64   :xyz is unbound
2d5e0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73  , then sqlite3_s
2d5f0 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e  ql() will return
2d600 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
2d610 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54   string, "SELECT
2d620 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20   $abc,:xyz" but 
2d630 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2d640 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72  _sql().** will r
2d650 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33  eturn "SELECT 23
2d660 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a  45,NULL".)^.**.*
2d670 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2d680 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e  xpanded_sql() in
2d690 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2d6a0 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
2d6b0 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69  ient memory.** i
2d6c0 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68  s available to h
2d6d0 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20  old the result, 
2d6e0 6f 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74  or if the result
2d6f0 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68   would exceed th
2d700 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d  e.** the maximum
2d710 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64   string length d
2d720 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
2d730 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c   [SQLITE_LIMIT_L
2d740 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ENGTH]..**.** ^T
2d750 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
2d760 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
2d770 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2d780 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65   limits the size
2d790 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72   of.** bound par
2d7a0 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e  ameter expansion
2d7b0 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  s.  ^The [SQLITE
2d7c0 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d  _OMIT_TRACE] com
2d7d0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
2d7e0 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74  ion causes sqlit
2d7f0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2d800 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75  ) to always retu
2d810 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  rn NULL..**.** ^
2d820 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2d830 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  ned by sqlite3_s
2d840 71 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64  ql(P) is managed
2d850 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69   by SQLite and i
2d860 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
2d870 6c 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68  ly freed when th
2d880 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2d890 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
2d8a0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  d..** ^The strin
2d8b0 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2d8c0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2d8d0 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74  ql(P), on the ot
2d8e0 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20  her hand,.** is 
2d8f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2d900 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2d910 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65   and must be fre
2d920 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  e by the applica
2d930 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69  tion.** by passi
2d940 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
2d950 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 53 51  3_free()]..*/.SQ
2d960 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2d970 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
2d980 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2d990 53 74 6d 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  Stmt);.SQLITE_AP
2d9a0 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
2d9b0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c  expanded_sql(sql
2d9c0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2d9d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d9e0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
2d9f0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2da00 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
2da10 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a  abase.** METHOD:
2da20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2da30 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2da40 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
2da50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2da60 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2da70 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
2da80 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
2da90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
2daa0 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
2dab0 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
2dac0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2dad0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
2dae0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2daf0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2db00 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2db10 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
2db20 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
2db30 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
2db40 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
2db50 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
2db60 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
2db70 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
2db80 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
2db90 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
2dba0 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
2dbb0 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
2dbc0 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
2dbd0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
2dbe0 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
2dbf0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2dc00 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
2dc10 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
2dc20 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2dc30 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
2dc40 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
2dc50 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
2dc60 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
2dc70 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
2dc80 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
2dc90 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2dca0 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
2dcb0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2dcc0 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
2dcd0 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
2dce0 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
2dcf0 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
2dd00 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
2dd10 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
2dd20 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
2dd30 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
2dd40 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
2dd50 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
2dd60 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
2dd70 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
2dd80 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
2dd90 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
2dda0 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
2ddb0 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
2ddc0 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
2ddd0 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
2dde0 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
2ddf0 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
2de00 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
2de10 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
2de20 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
2de30 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
2de40 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
2de50 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
2de60 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
2de70 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
2de80 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
2de90 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
2dea0 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
2deb0 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
2dec0 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
2ded0 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
2dee0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
2def0 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
2df00 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
2df10 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2df20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
2df30 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49  on disk..*/.SQLI
2df40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2df50 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2df60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2df70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2df80 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
2df90 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20  e If A Prepared 
2dfa0 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65  Statement Has Be
2dfb0 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48  en Reset.** METH
2dfc0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2dfd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2dfe0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
2dff0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2e000 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
2e010 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
2e020 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e030 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
2e040 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
2e050 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
2e060 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
2e070 75 74 20 68 61 73 20 6e 65 69 74 68 65 72 20 72  ut has neither r
2e080 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
2e090 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53   (returned.** [S
2e0a0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d  QLITE_DONE] from
2e0b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
2e0c0 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20  )]) nor.** been 
2e0d0 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c  reset using [sql
2e0e0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20  ite3_reset(S)]. 
2e0f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2e100 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e  mt_busy(S).** in
2e110 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2e120 66 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20  false if S is a 
2e130 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49  NULL pointer.  I
2e140 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a  f S is not a .**
2e150 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
2e160 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74  d is not a point
2e170 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70  er to a valid [p
2e180 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e190 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68  t].** object, th
2e1a0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
2e1b0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2e1c0 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69   probably undesi
2e1d0 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  rable..**.** Thi
2e1e0 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
2e1f0 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69  be used in combi
2e200 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  nation [sqlite3_
2e210 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20  next_stmt()].** 
2e220 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72  to locate all pr
2e230 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e240 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
2e250 68 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a  h a database .**
2e260 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
2e270 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20   are in need of 
2e280 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68  being reset.  Th
2e290 69 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a  is can be used,.
2e2a0 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** for example, 
2e2b0 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f  in diagnostic ro
2e2c0 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68  utines to search
2e2d0 20 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a   for prepared .*
2e2e0 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  * statements tha
2e2f0 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20  t are holding a 
2e300 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e  transaction open
2e310 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2e320 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
2e330 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74  _busy(sqlite3_st
2e340 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2e350 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c  I3REF: Dynamical
2e360 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f  ly Typed Value O
2e370 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
2e380 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71  S: {protected sq
2e390 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e  lite3_value} {un
2e3a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e3b0 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53  3_value}.**.** S
2e3c0 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
2e3d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2e3e0 65 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ect to represent
2e3f0 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74   all values.** t
2e400 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65  hat can be store
2e410 64 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20  d in a database 
2e420 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73  table. SQLite us
2e430 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e  es dynamic typin
2e440 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c  g.** for the val
2e450 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20  ues it stores.  
2e460 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69  ^Values stored i
2e470 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  n sqlite3_value 
2e480 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62  objects.** can b
2e490 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61  e integers, floa
2e4a0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2e4b0 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42  s, strings, BLOB
2e4c0 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  s, or NULL..**.*
2e4d0 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  * An sqlite3_val
2e4e0 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65  ue object may be
2e4f0 20 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74   either "protect
2e500 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63  ed" or "unprotec
2e510 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e  ted"..** Some in
2e520 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2e530 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2e540 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68  ite3_value.  Oth
2e550 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  er interfaces.**
2e560 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74   will accept eit
2e570 68 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20  her a protected 
2e580 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65  or an unprotecte
2e590 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2e5a0 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66  .** Every interf
2e5b0 61 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73  ace that accepts
2e5c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61   sqlite3_value a
2e5d0 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69  rguments specifi
2e5e0 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72  es.** whether or
2e5f0 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73   not it requires
2e600 20 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c   a protected sql
2e610 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54 68 65  ite3_value.  The
2e620 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2e630 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65 72 66  ue_dup()] interf
2e640 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2e650 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61 20 6e  to construct a n
2e660 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74 65 64  ew .** protected
2e670 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 66   sqlite3_value f
2e680 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  rom an unprotect
2e690 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2e6a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
2e6b0 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
2e6c0 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
2e6d0 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
2e6e0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
2e6f0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
2e700 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
2e710 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
2e720 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2e730 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
2e740 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
2e750 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
2e760 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
2e770 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
2e780 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
2e790 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
2e7a0 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
2e7b0 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
2e7c0 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
2e7d0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
2e7e0 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
2e7f0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
2e800 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
2e810 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
2e820 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
2e830 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
2e840 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
2e850 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2e860 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
2e870 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
2e880 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
2e890 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
2e8a0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
2e8b0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2e8c0 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
2e8d0 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
2e8e0 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
2e8f0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
2e900 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
2e910 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
2e920 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
2e930 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
2e940 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
2e950 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2e960 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2e970 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2e980 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e990 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
2e9a0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
2e9b0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
2e9c0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2e9d0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
2e9e0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
2e9f0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
2ea00 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
2ea10 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
2ea20 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2ea30 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
2ea40 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
2ea50 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2ea60 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2ea70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2ea80 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2ea90 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
2eaa0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2eab0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2eac0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
2ead0 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
2eae0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2eaf0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2eb00 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
2eb10 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
2eb20 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
2eb30 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
2eb40 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
2eb50 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
2eb60 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
2eb70 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2eb80 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
2eb90 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
2eba0 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
2ebb0 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
2ebc0 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
2ebd0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
2ebe0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
2ebf0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
2ec00 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
2ec10 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
2ec20 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2ec30 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
2ec40 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
2ec50 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
2ec60 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
2ec70 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
2ec80 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2ec90 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2eca0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
2ecb0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2ecc0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2ecd0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
2ece0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
2ecf0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
2ed00 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2ed10 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
2ed20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
2ed30 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
2ed40 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2ed50 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
2ed60 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
2ed70 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2ed80 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
2ed90 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2eda0 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
2edb0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2edc0 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
2edd0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2ede0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
2edf0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
2ee00 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
2ee10 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
2ee20 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2ee30 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
2ee40 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
2ee50 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2ee60 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
2ee70 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
2ee80 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
2ee90 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
2eea0 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
2eeb0 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45  r binding}.** ME
2eec0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2eed0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  mt.**.** ^(In th
2eee0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2eef0 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
2ef00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2ef10 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
2ef20 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
2ef30 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
2ef40 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
2ef50 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
2ef60 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
2ef70 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
2ef80 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2ef90 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
2efa0 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
2efb0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
2efc0 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
2efd0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2efe0 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
2eff0 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
2f000 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
2f010 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
2f020 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
2f030 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
2f040 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
2f050 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
2f060 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
2f070 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
2f080 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
2f090 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
2f0a0 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
2f0b0 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
2f0c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2f0d0 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
2f0e0 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
2f0f0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2f100 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
2f110 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2f120 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
2f130 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
2f140 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
2f150 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2f160 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
2f170 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2f180 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
2f190 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
2f1a0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
2f1b0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
2f1c0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
2f1d0 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
2f1e0 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
2f1f0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2f200 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
2f210 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
2f220 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
2f230 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
2f240 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
2f250 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
2f260 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
2f270 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
2f280 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
2f290 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
2f2a0 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
2f2b0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
2f2c0 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
2f2d0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
2f2e0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2f2f0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
2f300 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
2f310 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
2f320 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
2f330 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
2f340 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
2f350 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
2f360 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
2f370 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
2f380 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
2f390 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
2f3a0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
2f3b0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
2f3c0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
2f3d0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2f3e0 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
2f3f0 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
2f400 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
2f410 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2f420 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2f430 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
2f440 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
2f450 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  6().** or sqlite
2f460 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
2f470 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2f480 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
2f490 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20  parameter.** is 
2f4a0 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20  ignored and the 
2f4b0 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68  end result is th
2f4c0 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65  e same as sqlite
2f4d0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a  3_bind_null()..*
2f4e0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
2f4f0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
2f500 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
2f510 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
2f520 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2f530 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2f540 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
2f550 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
2f560 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2f570 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
2f580 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
2f590 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
2f5a0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2f5b0 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
2f5c0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2f5d0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2f5e0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2f5f0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2f600 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2f610 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  hen the length o
2f620 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
2f630 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2f640 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
2f650 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
2f660 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68  inator..** If th
2f670 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2f680 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2f690 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67  nd_blob() is neg
2f6a0 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74  ative, then.** t
2f6b0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2f6c0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2f6d0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
2f6e0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2f6f0 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
2f700 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2f710 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2f720 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 6f  _bind_text16() o
2f730 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2f740 65 78 74 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20  ext64() then.** 
2f750 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
2f760 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
2f770 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
2f780 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
2f790 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
2f7a0 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
2f7b0 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
2f7c0 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
2f7d0 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
2f7e0 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
2f7f0 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
2f800 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
2f810 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
2f820 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
2f830 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
2f840 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
2f850 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
2f860 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
2f870 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
2f880 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
2f890 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
2f8a0 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
2f8b0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2f8c0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2f8d0 74 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e  t to the BLOB an
2f8e0 64 20 73 74 72 69 6e 67 20 62 69 6e 64 69 6e 67  d string binding
2f8f0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
2f900 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75  s a destructor u
2f910 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  sed to dispose o
2f920 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a  f the BLOB or.**
2f930 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51   string after SQ
2f940 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65  Lite has finishe
2f950 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65  d with it.  ^The
2f960 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63   destructor is c
2f970 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70  alled.** to disp
2f980 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20  ose of the BLOB 
2f990 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69  or string even i
2f9a0 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 62 69  f the call to bi
2f9b0 6e 64 20 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a  nd API fails..**
2f9c0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2f9d0 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
2f9e0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
2f9f0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
2fa00 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
2fa10 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
2fa20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2fa30 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
2fa40 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
2fa50 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2fa60 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
2fa70 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2fa80 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
2fa90 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
2faa0 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
2fab0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
2fac0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2fad0 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
2fae0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
2faf0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
2fb00 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
2fb10 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
2fb20 54 68 65 20 73 69 78 74 68 20 61 72 67 75 6d 65  The sixth argume
2fb30 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
2fb40 6e 64 5f 74 65 78 74 36 34 28 29 20 6d 75 73 74  nd_text64() must
2fb50 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53   be one of.** [S
2fb60 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51  QLITE_UTF8], [SQ
2fb70 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51  LITE_UTF16], [SQ
2fb80 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f  LITE_UTF16BE], o
2fb90 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  r [SQLITE_UTF16L
2fba0 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63 69 66 79  E].** to specify
2fbb0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66   the encoding of
2fbc0 20 74 68 65 20 74 65 78 74 20 69 6e 20 74 68 65   the text in the
2fbd0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2fbe0 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20 73 69 78  .  If.** the six
2fbf0 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2fc00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2fc10 36 34 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20  64() is not one 
2fc20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65  of the.** allowe
2fc30 64 20 76 61 6c 75 65 73 20 73 68 6f 77 6e 20 61  d values shown a
2fc40 62 6f 76 65 2c 20 6f 72 20 69 66 20 74 68 65 20  bove, or if the 
2fc50 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 69 73  text encoding is
2fc60 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72   different.** fr
2fc70 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  om the encoding 
2fc80 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
2fc90 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
2fca0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2fcb0 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  ior.** is undefi
2fcc0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2fcd0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2fce0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
2fcf0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
2fd00 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
2fd10 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
2fd20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
2fd30 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
2fd40 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
2fd50 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
2fd60 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
2fd70 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
2fd80 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
2fd90 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
2fda0 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
2fdb0 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
2fdc0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
2fdd0 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
2fde0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
2fdf0 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
2fe00 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
2fe10 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
2fe20 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
2fe30 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
2fe40 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
2fe50 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
2fe60 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
2fe70 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
2fe80 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
2fe90 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2fea0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2feb0 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
2fec0 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
2fed0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2fee0 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
2fef0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ff00 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
2ff10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2ff20 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
2ff30 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
2ff40 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
2ff50 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
2ff60 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
2ff70 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
2ff80 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
2ff90 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
2ffa0 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
2ffb0 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
2ffc0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2ffd0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2ffe0 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
2fff0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
30000 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
30010 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
30020 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
30030 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
30040 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
30050 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
30060 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
30070 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
30080 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
30090 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
300a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
300b0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
300c0 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
300d0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
300e0 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
300f0 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
30100 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74 20 62 65  TOOBIG] might be
30110 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68 65   returned if the
30120 20 73 69 7a 65 20 6f 66 20 61 20 73 74 72 69 6e   size of a strin
30130 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63  g or BLOB.** exc
30140 65 65 64 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f  eeds limits impo
30150 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  sed by [sqlite3_
30160 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c  limit]([SQLITE_L
30170 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72  IMIT_LENGTH]) or
30180 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f  .** [SQLITE_MAX_
30190 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51  LENGTH]..** ^[SQ
301a0 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
301b0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
301c0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
301d0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
301e0 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
301f0 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
30200 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
30210 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
30220 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
30230 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
30240 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
30250 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
30260 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
30270 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30280 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
30290 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
302a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
302b0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
302c0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
302d0 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
302e0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
302f0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
30300 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73  e3_bind_blob64(s
30310 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
30320 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
30330 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a  sqlite3_uint64,.
30340 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30350 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28          void(*)(
30360 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
30370 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
30380 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
30390 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
303a0 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f  double);.SQLITE_
303b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
303c0 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
303d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
303e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
303f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
30400 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
30410 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
30420 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f  _int64);.SQLITE_
30430 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
30440 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
30450 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53  3_stmt*, int);.S
30460 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
30470 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
30480 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
30490 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 69 6e  t,const char*,in
304a0 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  t,void(*)(void*)
304b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
304c0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
304d0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
304e0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
304f0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
30500 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
30510 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
30520 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
30530 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
30540 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
30550 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
30560 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
30570 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
30580 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e  )(void*), unsign
30590 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67  ed char encoding
305a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
305b0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
305c0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
305d0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
305e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
305f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
30600 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
30610 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
30620 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
30630 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
30640 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
30650 6f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f  oblob64(sqlite3_
30660 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
30670 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a  te3_uint64);../*
30680 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
30690 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
306a0 6d 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44  meters.** METHOD
306b0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
306c0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
306d0 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ne can be used t
306e0 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
306f0 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65  r of [SQL parame
30700 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70  ters].** in a [p
30710 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30720 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74  t].  SQL paramet
30730 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f  ers are tokens o
30740 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f  f the.** form "?
30750 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41  ", "?NNN", ":AAA
30760 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40  ", "$AAA", or "@
30770 41 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20  AAA" that serve 
30780 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65  as.** placeholde
30790 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68  rs for values th
307a0 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f  at are [sqlite3_
307b0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e  bind_blob | boun
307c0 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72  d].** to the par
307d0 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74  ameters at a lat
307e0 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  er time..**.** ^
307f0 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63  (This routine ac
30800 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74  tually returns t
30810 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
30820 6c 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f  largest (rightmo
30830 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  st).** parameter
30840 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20  . For all forms 
30850 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69  except ?NNN, thi
30860 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e  s will correspon
30870 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  d to the.** numb
30880 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72  er of unique par
30890 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72  ameters.  If par
308a0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f  ameters of the ?
308b0 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65  NNN form are use
308c0 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20  d,.** there may 
308d0 62 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c  be gaps in the l
308e0 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ist.)^.**.** See
308f0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
30900 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
30910 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
30920 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
30930 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
30940 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
30950 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
30960 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
30970 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
30980 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30990 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
309a0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
309b0 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
309c0 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
309d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
309e0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
309f0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
30a00 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
30a10 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
30a20 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
30a30 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
30a40 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
30a50 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
30a60 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
30a70 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
30a80 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
30a90 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
30aa0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
30ab0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
30ac0 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
30ad0 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
30ae0 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
30af0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
30b00 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
30b10 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
30b20 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
30b30 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
30b40 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
30b50 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
30b60 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
30b70 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
30b80 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
30b90 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
30ba0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
30bb0 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
30bc0 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
30bd0 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
30be0 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
30bf0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
30c00 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
30c10 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
30c20 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
30c30 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
30c40 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
30c50 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
30c60 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
30c70 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
30c80 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
30c90 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
30ca0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
30cb0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
30cc0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
30cd0 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
30ce0 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
30cf0 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
30d00 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
30d10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
30d20 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
30d30 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
30d40 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
30d50 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
30d60 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
30d70 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
30d80 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30d90 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
30da0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
30db0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
30dc0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
30dd0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
30de0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
30df0 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
30e00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
30e10 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
30e20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
30e30 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
30e40 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44  n Name.** METHOD
30e50 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
30e60 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
30e70 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
30e80 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
30e90 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
30ea0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
30eb0 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
30ec0 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
30ed0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
30ee0 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
30ef0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
30f00 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
30f10 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
30f20 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
30f30 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
30f40 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
30f50 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
30f60 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
30f70 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
30f80 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
30f90 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
30fa0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
30fb0 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
30fc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
30fd0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
30fe0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
30ff0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
31000 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
31010 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
31020 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
31030 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
31040 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
31050 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  _name()]..*/.SQL
31060 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
31070 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
31080 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
31090 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
310a0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
310b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
310c0 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
310d0 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
310e0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f  atement.** METHO
310f0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
31100 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
31110 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
31120 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
31130 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
31140 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
31150 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
31160 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
31170 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
31180 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
31190 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
311a0 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
311b0 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
311c0 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45   NULL..*/.SQLITE
311d0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
311e0 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
311f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
31200 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31210 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d   Number Of Colum
31220 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  ns In A Result S
31230 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  et.** METHOD: sq
31240 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
31250 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
31260 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
31270 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
31280 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
31290 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
312a0 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20  atement]. ^This 
312b0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
312c0 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
312d0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
312e0 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
312f0 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
31300 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
31310 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ATE])..**.** See
31320 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
31330 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
31340 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
31350 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
31360 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
31370 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
31380 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
31390 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
313a0 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48  sult Set.** METH
313b0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
313c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
313d0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
313e0 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20  e name assigned 
313f0 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  to a particular 
31400 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65  column.** in the
31410 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
31420 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
31430 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ent.  ^The sqlit
31440 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
31450 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
31460 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
31470 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
31480 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
31490 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  g.** and sqlite3
314a0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
314b0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
314c0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
314d0 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
314e0 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20  6 string.  ^The 
314f0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
31500 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  is the [prepared
31510 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74   statement].** t
31520 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
31530 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
31540 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f  ement. ^The seco
31550 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
31560 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75  the.** column nu
31570 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74  mber.  ^The left
31580 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e  most column is n
31590 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e  umber 0..**.** ^
315a0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
315b0 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76  ing pointer is v
315c0 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65  alid until eithe
315d0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
315e0 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73  statement].** is
315f0 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73   destroyed by [s
31600 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
31610 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
31620 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
31630 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
31640 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
31650 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
31660 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
31670 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
31680 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
31690 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f  the next call to
316a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
316b0 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c  mn_name() or sql
316c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
316d0 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65  16() on the same
316e0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
316f0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
31700 63 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67  c() fails during
31710 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20   the processing 
31720 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e  of either routin
31730 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c  e.** (for exampl
31740 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65  e during a conve
31750 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38  rsion from UTF-8
31760 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e   to UTF-16) then
31770 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
31780 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
31790 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
317a0 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75  of a result colu
317b0 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  mn is the value 
317c0 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75  of the "AS" clau
317d0 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63  se for.** that c
317e0 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20  olumn, if there 
317f0 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e  is an AS clause.
31800 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f    If there is no
31810 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68   AS clause.** th
31820 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  en the name of t
31830 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73  he column is uns
31840 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79  pecified and may
31850 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20   change from.** 
31860 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  one release of S
31870 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78  QLite to the nex
31880 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
31890 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
318a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
318b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
318c0 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
318d0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
318e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
318f0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
31900 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
31910 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
31920 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
31930 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
31940 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
31950 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
31960 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
31970 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
31980 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
31990 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
319a0 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
319b0 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
319c0 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
319d0 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
319e0 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
319f0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
31a00 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
31a10 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
31a20 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
31a30 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
31a40 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
31a50 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
31a60 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
31a70 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
31a80 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
31a90 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
31aa0 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
31ab0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
31ac0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
31ad0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
31ae0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
31af0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
31b00 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
31b10 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
31b20 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
31b30 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
31b40 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
31b50 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
31b60 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
31b70 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
31b80 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
31b90 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
31ba0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
31bb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
31bc0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
31bd0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
31be0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
31bf0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
31c00 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
31c10 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
31c20 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
31c30 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
31c40 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
31c50 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
31c60 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
31c70 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
31c80 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
31c90 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
31ca0 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
31cb0 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
31cc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
31cd0 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
31ce0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
31cf0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
31d00 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
31d10 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
31d20 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
31d30 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
31d40 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
31d50 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
31d60 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
31d70 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
31d80 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
31d90 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
31da0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
31db0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
31dc0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
31dd0 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
31de0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
31df0 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
31e00 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
31e10 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
31e20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
31e30 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
31e40 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
31e50 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
31e60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
31e70 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
31e80 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
31e90 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
31ea0 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
31eb0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
31ec0 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
31ed0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
31ee0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
31ef0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
31f00 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
31f10 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
31f20 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
31f30 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
31f40 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
31f50 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
31f60 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
31f70 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
31f80 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
31f90 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
31fa0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
31fb0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
31fc0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
31fd0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
31fe0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
31ff0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
32000 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
32010 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
32020 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
32030 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
32040 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
32050 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
32060 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
32070 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
32080 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
32090 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
320a0 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
320b0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
320c0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
320d0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
320e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
320f0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
32100 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
32110 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
32120 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
32130 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32140 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
32150 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
32160 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
32170 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
32180 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51  undefined..*/.SQ
32190 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
321a0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
321b0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
321c0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
321d0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
321e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
321f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
32200 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
32210 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
32220 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
32230 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
32240 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
32250 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32260 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
32270 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
32280 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
32290 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
322a0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
322b0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
322c0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
322d0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
322e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
322f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
32300 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
32310 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
32320 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
32330 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
32340 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
32350 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
32360 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
32370 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
32380 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  3_stmt.**.** ^(T
32390 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
323a0 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
323b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
323c0 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
323d0 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
323e0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
323f0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
32400 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
32410 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
32420 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
32430 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
32440 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
32450 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
32460 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
32470 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
32480 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
32490 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
324a0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
324b0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
324c0 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
324d0 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
324e0 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
324f0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
32500 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
32510 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
32520 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
32530 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
32540 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
32550 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
32560 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
32570 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
32580 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
32590 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
325a0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
325b0 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
325c0 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
325d0 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
325e0 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
325f0 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
32600 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
32610 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
32620 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
32630 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
32640 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
32650 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
32660 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
32670 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
32680 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
32690 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
326a0 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
326b0 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
326c0 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
326d0 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
326e0 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
326f0 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
32700 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
32710 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
32720 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
32730 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
32740 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
32750 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
32760 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
32770 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
32780 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
32790 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
327a0 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
327b0 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
327c0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
327d0 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
327e0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
327f0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
32800 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
32810 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
32820 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
32830 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
32840 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
32850 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ype16(sqlite3_st
32860 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
32870 20 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75   CAPI3REF: Evalu
32880 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ate An SQL State
32890 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ment.** METHOD: 
328a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
328b0 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
328c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
328d0 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
328e0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
328f0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
32900 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
32910 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
32920 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
32930 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
32940 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
32950 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
32960 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
32970 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
32980 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
32990 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
329a0 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
329b0 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
329c0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
329d0 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
329e0 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
329f0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
32a00 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
32a10 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
32a20 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
32a30 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
32a40 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
32a50 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
32a60 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
32a70 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
32a80 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
32a90 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
32aa0 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
32ab0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
32ac0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
32ad0 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
32ae0 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
32af0 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
32b00 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
32b10 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
32b20 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
32b30 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
32b40 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
32b50 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
32b60 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
32b70 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
32b80 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
32b90 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
32ba0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
32bb0 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
32bc0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
32bd0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
32be0 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
32bf0 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
32c00 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
32c10 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
32c20 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
32c30 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
32c40 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
32c50 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
32c60 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
32c70 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
32c80 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
32c90 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
32ca0 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
32cb0 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
32cc0 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
32cd0 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
32ce0 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
32cf0 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
32d00 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
32d10 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
32d20 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
32d30 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
32d40 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
32d50 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
32d60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
32d70 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
32d80 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
32d90 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
32da0 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
32db0 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
32dc0 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
32dd0 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
32de0 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
32df0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
32e00 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
32e10 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
32e20 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
32e30 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
32e40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
32e50 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
32e60 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
32e70 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
32e80 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
32e90 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
32ea0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
32eb0 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
32ec0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
32ed0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
32ee0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
32ef0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
32f00 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
32f10 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
32f20 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
32f30 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
32f40 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
32f50 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
32f60 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
32f70 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
32f80 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
32f90 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
32fa0 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
32fb0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
32fc0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
32fd0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
32fe0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
32ff0 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
33000 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
33010 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
33020 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
33030 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
33040 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
33050 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
33060 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
33070 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
33080 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
33090 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
330a0 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
330b0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
330c0 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
330d0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
330e0 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
330f0 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
33100 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
33110 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
33120 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
33130 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
33140 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
33150 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
33160 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
33170 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
33180 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
33190 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
331a0 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
331b0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
331c0 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
331d0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
331e0 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
331f0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
33200 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
33210 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
33220 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
33230 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
33240 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
33250 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
33260 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
33270 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
33280 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
33290 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
332a0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
332b0 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
332c0 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
332d0 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
332e0 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
332f0 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
33300 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
33310 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
33320 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
33330 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
33340 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
33350 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
33360 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
33370 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
33380 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
33390 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
333a0 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
333b0 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
333c0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
333d0 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
333e0 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
333f0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
33400 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
33410 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
33420 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
33430 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
33440 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
33450 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
33460 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
33470 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
33480 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
33490 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
334a0 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
334b0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
334c0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
334d0 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
334e0 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
334f0 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
33500 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
33510 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
33520 61 66 74 65 72 20 5b 76 65 72 73 69 6f 6e 20 33  after [version 3
33530 2e 36 2e 32 33 2e 31 5d 20 28 5b 64 61 74 65 6f  .6.23.1] ([dateo
33540 66 3a 33 2e 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20  f:3.6.23.1],.** 
33550 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
33560 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
33570 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
33580 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
33590 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
335a0 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
335b0 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
335c0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
335d0 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
335e0 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
335f0 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
33600 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
33610 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
33620 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
33630 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
33640 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
33650 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
33660 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
33670 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
33680 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
33690 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
336a0 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
336b0 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
336c0 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
336d0 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
336e0 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
336f0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
33700 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
33710 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
33720 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
33730 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
33740 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
33750 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
33760 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
33770 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
33780 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
33790 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
337a0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
337b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
337c0 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
337d0 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
337e0 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
337f0 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
33800 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
33810 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
33820 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
33830 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
33840 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
33850 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
33860 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
33870 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
33880 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
33890 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
338a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
338b0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
338c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
338d0 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
338e0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
338f0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
33900 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
33910 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
33920 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
33930 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
33940 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
33950 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
33960 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
33970 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
33980 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
33990 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
339a0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
339b0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
339c0 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ended..*/.SQLITE
339d0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
339e0 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
339f0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
33a00 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
33a10 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
33a20 73 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48  sult set.** METH
33a30 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
33a40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33a50 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
33a60 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
33a70 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
33a80 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
33a90 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
33aa0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
33ab0 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
33ac0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
33ad0 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
33ae0 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
33af0 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
33b00 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
33b10 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
33b20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
33b30 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
33b40 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
33b50 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
33b60 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
33b70 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
33b80 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
33b90 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
33ba0 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
33bb0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
33bc0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
33bd0 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  r..** ^The sqlit
33be0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
33bf0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
33c00 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f   0 if the previo
33c10 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  us call to.** [s
33c20 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
33c30 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
33c40 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71  _DONE].  ^The sq
33c50 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
33c60 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  (P).** will retu
33c70 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70  rn non-zero if p
33c80 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
33c90 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
33ca0 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53  ) returned.** [S
33cb0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65  QLITE_ROW], exce
33cc0 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f  pt in the case o
33cd0 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e  f the [PRAGMA in
33ce0 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d  cremental_vacuum
33cf0 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c  ].** where it al
33d00 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72  ways returns zer
33d10 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65  o since each ste
33d20 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d  p of that multi-
33d30 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72  step.** pragma r
33d40 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73  eturns 0 columns
33d50 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
33d60 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
33d70 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
33d80 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )].*/.SQLITE_API
33d90 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74   int sqlite3_dat
33da0 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
33db0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
33dc0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
33dd0 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
33de0 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
33df0 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
33e00 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
33e10 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
33e20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
33e30 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
33e40 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
33e50 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
33e60 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
33e70 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
33e80 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
33e90 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
33ea0 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
33eb0 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
33ec0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
33ed0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
33ee0 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
33ef0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
33f00 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
33f10 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
33f20 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
33f30 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
33f40 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
33f50 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
33f60 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
33f70 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
33f80 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
33f90 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
33fa0 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
33fb0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
33fc0 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
33fd0 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
33fe0 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
33ff0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
34000 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
34010 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
34020 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
34030 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
34040 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
34050 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
34060 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
34070 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
34080 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
34090 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
340a0 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
340b0 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
340c0 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
340d0 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
340e0 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
340f0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
34100 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
34110 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
34120 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
34130 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
34140 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
34150 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
34160 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
34170 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
34180 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
34190 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
341a0 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
341b0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
341c0 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
341d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
341e0 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
341f0 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
34200 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
34210 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
34220 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
34230 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
34240 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
34250 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
34260 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
34270 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
34280 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
34290 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
342a0 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
342b0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
342c0 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
342d0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
342e0 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
342f0 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
34300 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
34310 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
34320 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
34330 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
34340 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
34350 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
34360 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
34370 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
34380 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
34390 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
343a0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
343b0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
343c0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
343d0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
343e0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
343f0 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
34400 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
34410 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
34420 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
34430 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
34440 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
34450 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
34460 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
34470 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34480 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
34490 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
344a0 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
344b0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
344c0 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
344d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
344e0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
344f0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
34500 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
34510 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
34520 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
34530 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
34540 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
34550 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
34560 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
34570 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
34580 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
34590 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
345a0 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
345b0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
345c0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
345d0 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
345e0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
345f0 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
34600 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
34610 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
34620 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
34630 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
34640 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
34650 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
34660 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
34670 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
34680 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
34690 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
346a0 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
346b0 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
346c0 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
346d0 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
346e0 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
346f0 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
34700 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
34710 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
34720 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
34730 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
34740 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
34750 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
34760 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
34770 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
34780 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
34790 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
347a0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
347b0 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
347c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
347d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
347e0 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
347f0 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
34800 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
34810 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
34820 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
34830 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
34840 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
34850 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
34860 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
34870 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
34880 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
34890 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
348a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
348b0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
348c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
348d0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
348e0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
348f0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
34900 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
34910 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
34920 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
34930 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
34940 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
34950 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
34960 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
34970 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
34980 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
34990 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
349a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
349b0 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
349c0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
349d0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
349e0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
349f0 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
34a00 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
34a10 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
34a20 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
34a30 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
34a40 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
34a50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34a60 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
34a70 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
34a80 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
34a90 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
34aa0 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
34ab0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
34ac0 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
34ad0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
34ae0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
34af0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
34b00 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
34b10 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
34b20 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
34b30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
34b40 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
34b50 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
34b60 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
34b70 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
34b80 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
34b90 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
34ba0 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
34bb0 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
34bc0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
34bd0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
34be0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
34bf0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
34c00 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
34c10 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
34c20 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
34c30 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
34c40 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
34c50 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
34c60 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
34c70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
34c80 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
34c90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
34ca0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
34cb0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
34cc0 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
34cd0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
34ce0 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
34cf0 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
34d00 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
34d10 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
34d20 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
34d30 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
34d40 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
34d50 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
34d60 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
34d70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
34d80 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
34d90 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
34da0 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
34db0 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
34dc0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
34dd0 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
34de0 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
34df0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
34e00 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
34e10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
34e20 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
34e30 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
34e40 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
34e50 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
34e60 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
34e70 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
34e80 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
34e90 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
34ea0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
34eb0 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69  ..**.** <b>Warni
34ec0 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65 20 6f 62 6a  ng:</b> ^The obj
34ed0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
34ee0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
34ef0 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
34f00 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
34f10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34f20 6a 65 63 74 2e 20 20 49 6e 20 61 20 6d 75 6c 74  ject.  In a mult
34f30 69 74 68 72 65 61 64 65 64 20 65 6e 76 69 72 6f  ithreaded enviro
34f40 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70  nment,.** an unp
34f50 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
34f60 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
34f70 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 73  y only be used s
34f80 61 66 65 6c 79 20 77 69 74 68 0a 2a 2a 20 5b 73  afely with.** [s
34f90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
34fa0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
34fb0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
34fc0 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
34fd0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
34fe0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
34ff0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
35000 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
35010 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
35020 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
35030 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
35040 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
35050 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
35060 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
35070 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
35080 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
35090 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
350a0 29 5d 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  )], the behavior
350b0 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
350c0 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  fe..**.** These 
350d0 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
350e0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
350f0 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
35100 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
35110 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
35120 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
35130 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
35140 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
35150 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
35160 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
35170 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
35180 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
35190 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
351a0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
351b0 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
351c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
351d0 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
351e0 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
351f0 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
35200 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
35210 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
35220 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
35230 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
35240 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
35250 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
35260 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
35270 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
35280 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
35290 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
352a0 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
352b0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
352c0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
352d0 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
352e0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
352f0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
35300 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
35310 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
35320 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
35330 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
35340 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
35350 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
35360 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
35370 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
35380 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
35390 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
353a0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
353b0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
353c0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
353d0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
353e0 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
353f0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
35400 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
35410 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
35420 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
35430 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
35440 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
35450 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
35460 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
35470 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
35480 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
35490 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
354a0 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
354b0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
354c0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
354d0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
354e0 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64   BLOB.** <tr><td
354f0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
35500 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
35510 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
35520 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
35530 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
35540 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
35550 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
35560 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
35570 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
35580 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
35590 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
355a0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
355b0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
355c0 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
355d0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
355e0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
355f0 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
35600 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
35610 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
35620 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
35630 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
35640 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
35650 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
35660 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ote>)^.**.** Not
35670 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
35680 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
35690 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
356a0 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
356b0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
356c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
356d0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
356e0 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
356f0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
35700 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
35710 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
35720 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
35730 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
35740 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
35750 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
35760 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
35770 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
35780 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
35790 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
357a0 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
357b0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
357c0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
357d0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
357e0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
357f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
35800 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
35810 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
35820 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
35830 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
35840 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
35850 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
35860 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35870 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
35880 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
35890 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
358a0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
358b0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
358c0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
358d0 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
358e0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
358f0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
35900 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
35910 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
35920 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
35930 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35940 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
35950 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
35960 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
35970 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
35980 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
35990 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
359a0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
359b0 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
359c0 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
359d0 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
359e0 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
359f0 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
35a00 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
35a10 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
35a20 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
35a30 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
35a40 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
35a50 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
35a60 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
35a70 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
35a80 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
35a90 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
35aa0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
35ab0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
35ac0 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
35ad0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
35ae0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
35af0 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
35b00 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
35b10 2a 20 54 68 65 20 73 61 66 65 73 74 20 70 6f 6c  * The safest pol
35b20 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
35b30 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
35b40 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
35b50 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
35b60 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
35b70 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
35b80 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
35b90 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
35ba0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
35bb0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
35bc0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
35bd0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
35be0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35bf0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
35c00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
35c10 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
35c20 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
35c30 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
35c40 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
35c50 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
35c60 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
35c70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35c80 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
35c90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
35ca0 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
35cb0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
35cc0 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
35cd0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
35ce0 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
35cf0 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
35d00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
35d10 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
35d20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
35d30 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
35d40 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
35d50 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
35d60 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
35d70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35d80 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
35d90 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
35da0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
35db0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35dc0 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
35dd0 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
35de0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
35df0 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
35e00 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
35e10 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
35e20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
35e30 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
35e40 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
35e50 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
35e60 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
35e70 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
35e80 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
35e90 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
35ea0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
35eb0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
35ec0 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
35ed0 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
35ee0 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
35ef0 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
35f00 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
35f10 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
35f20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20  Do <em>not</em> 
35f30 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72  pass the pointer
35f40 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  s returned.** fr
35f50 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
35f60 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
35f70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35f80 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
35f90 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
35fa0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
35fb0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
35fc0 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
35fd0 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
35fe0 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
35ff0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
36000 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
36010 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
36020 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
36030 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
36040 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
36050 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
36060 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
36070 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
36080 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
36090 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
360a0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
360b0 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
360c0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
360d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
360e0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
360f0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69  column_blob(sqli
36100 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
36110 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
36120 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
36130 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65  umn_bytes(sqlite
36140 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
36150 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
36160 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
36170 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
36180 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
36190 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64  l);.SQLITE_API d
361a0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
361b0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
361c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
361d0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
361e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
361f0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
36200 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
36210 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
36220 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
36230 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28  e3_column_int64(
36240 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
36250 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
36260 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67  _API const unsig
36270 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
36280 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71  3_column_text(sq
36290 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
362a0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
362b0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
362c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
362d0 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  xt16(sqlite3_stm
362e0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
362f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
36300 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
36310 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
36320 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
36330 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76  TE_API sqlite3_v
36340 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f  alue *sqlite3_co
36350 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74  lumn_value(sqlit
36360 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
36370 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ol);../*.** CAPI
36380 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20  3REF: Destroy A 
36390 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
363a0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 44 45 53  nt Object.** DES
363b0 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33  TRUCTOR: sqlite3
363c0 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
363d0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
363e0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
363f0 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
36400 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
36410 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
36420 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
36430 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
36440 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
36450 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
36460 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
36470 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
36480 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
36490 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
364a0 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
364b0 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
364c0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
364d0 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
364e0 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
364f0 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
36500 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
36510 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
36520 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
36530 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
36540 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
36550 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
36560 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
36570 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
36580 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
36590 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
365a0 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
365b0 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
365c0 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
365d0 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
365e0 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
365f0 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
36600 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
36610 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
36620 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
36630 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
36640 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
36650 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
36660 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
36670 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
36680 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
36690 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
366a0 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
366b0 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
366c0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
366d0 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
366e0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
366f0 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
36700 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
36710 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
36720 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
36730 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
36740 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
36750 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
36760 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
36770 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
36780 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
36790 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
367a0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
367b0 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
367c0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
367d0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
367e0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
367f0 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
36800 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
36810 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
36820 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
36830 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
36840 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
36850 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
36860 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
36870 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
36880 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
36890 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50  I3REF: Reset A P
368a0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
368b0 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4d 45 54 48  t Object.** METH
368c0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
368d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
368e0 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
368f0 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
36900 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
36910 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
36920 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
36930 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
36940 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
36950 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
36960 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
36970 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
36980 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
36990 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
369a0 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
369b0 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
369c0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
369d0 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
369e0 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
369f0 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
36a00 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
36a10 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
36a20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
36a30 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
36a40 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
36a50 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
36a60 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
36a70 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
36a80 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
36a90 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
36aa0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
36ab0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
36ac0 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
36ad0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
36ae0 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
36af0 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
36b00 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
36b10 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
36b20 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
36b30 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
36b40 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
36b50 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
36b60 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
36b70 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
36b80 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
36b90 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
36ba0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
36bb0 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
36bc0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
36bd0 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
36be0 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
36bf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
36c00 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
36c10 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
36c20 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
36c30 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
36c40 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
36c50 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
36c60 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
36c70 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
36c80 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
36c90 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
36ca0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
36cb0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
36cc0 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
36cd0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
36ce0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
36cf0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
36d00 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
36d10 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
36d20 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
36d30 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
36d40 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
36d50 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
36d60 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
36d70 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
36d80 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
36d90 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
36da0 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
36db0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
36dc0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
36dd0 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
36de0 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
36df0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
36e00 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
36e10 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
36e20 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
36e30 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
36e40 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
36e50 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
36e60 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
36e70 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
36e80 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
36e90 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
36ea0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
36eb0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
36ec0 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
36ed0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
36ee0 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
36ef0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
36f00 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
36f10 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
36f20 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
36f30 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
36f40 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
36f50 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
36f60 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
36f70 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
36f80 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
36f90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36fa0 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
36fb0 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
36fc0 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
36fd0 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
36fe0 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
36ff0 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
37000 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
37010 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
37020 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
37030 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
37040 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
37050 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37060 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
37070 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
37080 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
37090 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
370a0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
370b0 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
370c0 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
370d0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
370e0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
370f0 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
37100 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
37110 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
37120 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
37130 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
37140 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
37150 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
37160 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
37170 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
37180 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
37190 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
371a0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
371b0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
371c0 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
371d0 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
371e0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
371f0 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
37200 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
37210 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
37220 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
37230 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
37240 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
37250 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
37260 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
37270 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
37280 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
37290 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
372a0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
372b0 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
372c0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
372d0 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
372e0 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
372f0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
37300 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
37310 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
37320 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
37330 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
37340 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
37350 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
37360 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
37370 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
37380 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
37390 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
373a0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
373b0 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
373c0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
373d0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
373e0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
373f0 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
37400 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
37410 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
37420 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
37430 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
37440 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
37450 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
37460 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
37470 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
37480 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
37490 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
374a0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
374b0 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
374c0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
374d0 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
374e0 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
374f0 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
37500 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
37510 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
37520 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
37530 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
37540 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
37550 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
37560 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
37570 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
37580 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
37590 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
375a0 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
375b0 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
375c0 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
375d0 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
375e0 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
375f0 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
37600 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
37610 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
37620 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
37630 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
37640 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
37650 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
37660 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
37670 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
37680 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
37690 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
376a0 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
376b0 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
376c0 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
376d0 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
376e0 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
376f0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
37700 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
37710 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
37720 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
37730 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
37740 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
37750 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
37760 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
37770 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
37780 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
37790 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
377a0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
377b0 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
377c0 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
377d0 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
377e0 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
377f0 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
37800 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
37810 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
37820 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
37830 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
37840 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
37850 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
37860 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
37870 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
37880 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
37890 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
378a0 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
378b0 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
378c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
378d0 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
378e0 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
378f0 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
37900 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
37910 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
37920 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
37930 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
37940 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
37950 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
37960 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
37970 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
37980 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
37990 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
379a0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
379b0 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
379c0 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
379d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
379e0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
379f0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
37a00 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
37a10 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
37a20 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
37a30 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
37a40 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
37a50 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
37a60 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
37a70 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
37a80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37a90 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
37aa0 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
37ab0 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
37ac0 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
37ad0 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
37ae0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
37af0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
37b00 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
37b10 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
37b20 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
37b30 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
37b40 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
37b50 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
37b60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
37b70 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
37b80 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
37b90 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
37ba0 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
37bb0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
37bc0 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
37bd0 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
37be0 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
37bf0 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
37c00 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
37c10 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
37c20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
37c30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
37c40 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
37c50 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
37c60 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
37c70 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
37c80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
37c90 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
37ca0 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
37cb0 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
37cc0 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
37cd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
37ce0 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
37cf0 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
37d00 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
37d10 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
37d20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
37d30 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
37d40 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
37d50 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
37d60 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
37d70 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
37d80 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
37d90 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
37da0 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
37db0 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
37dc0 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
37dd0 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
37de0 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
37df0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
37e00 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
37e10 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
37e20 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
37e30 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
37e40 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
37e50 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
37e60 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
37e70 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
37e80 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
37e90 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
37ea0 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
37eb0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
37ec0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
37ed0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
37ee0 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
37ef0 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
37f00 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
37f10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
37f20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
37f30 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
37f40 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
37f50 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
37f60 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
37f70 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
37f80 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
37f90 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
37fa0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
37fb0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
37fc0 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
37fd0 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
37fe0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
37ff0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
38000 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
38010 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
38020 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
38030 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
38040 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
38050 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
38060 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
38070 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
38080 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
38090 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
380a0 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
380b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
380c0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
380d0 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
380e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
380f0 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
38100 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
38110 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
38120 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
38130 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
38140 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
38150 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
38160 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
38170 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
38180 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
38190 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
381a0 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
381b0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
381c0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
381d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
381e0 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
381f0 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
38200 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
38210 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
38220 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
38230 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
38240 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
38250 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
38260 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
38270 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
38280 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38290 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
382a0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
382b0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
382c0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51  _context*).);.SQ
382d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
382e0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
382f0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
38300 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76  3 *db,.  const v
38310 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  oid *zFunctionNa
38320 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
38330 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
38340 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
38350 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
38360 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
38370 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
38380 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
38390 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
383a0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
383b0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
383c0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
383d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
383e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
383f0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
38400 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
38410 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
38420 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
38430 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
38440 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
38450 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
38460 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
38470 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
38480 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
38490 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
384a0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
384b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
384c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
384d0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
384e0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
384f0 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
38500 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
38510 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38520 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
38530 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
38540 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
38550 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
38560 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
38570 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
38580 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
38590 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
385a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
385b0 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20  TF8           1 
385c0 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35     /* IMP: R-375
385d0 31 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66  14-35566 */.#def
385e0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
385f0 4c 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f  LE        2    /
38600 2a 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33  * IMP: R-03371-3
38610 37 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20  7637 */.#define 
38620 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20  SQLITE_UTF16BE  
38630 20 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d        3    /* IM
38640 50 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34  P: R-51971-34154
38650 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
38660 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20  TE_UTF16        
38670 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61    4    /* Use na
38680 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
38690 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
386a0 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20  E_ANY           
386b0 20 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61   5    /* Depreca
386c0 74 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ted */.#define S
386d0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
386e0 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
386f0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
38700 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
38710 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
38720 75 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a  unction Flags.