System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 76fce7ead65484ef472dee67279d2b39260f1e99:


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 39 2e 32 2e 20 20  ersion 3.19.2.  
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c  By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74  C code files int
00e0: 6f 20 74 68 69 73 0a 2a 2a 20 73 69 6e 67 6c 65  o this.** single
00f0: 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68 65   large file, the
0100: 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61 6e   entire code can
0110: 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73 20   be compiled as 
0120: 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c 61  a single transla
0130: 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20 54  tion.** unit.  T
0140: 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79 20  his allows many 
0150: 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f 20  compilers to do 
0160: 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74 68  optimizations th
0170: 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65 0a  at would not be.
0180: 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20 74  ** possible if t
0190: 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63 6f  he files were co
01a0: 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65 6c  mpiled separatel
01b0: 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65 20  y.  Performance 
01c0: 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a 20  improvements.** 
01d0: 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61 72  of 5% or more ar
01e0: 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e 20  e commonly seen 
01f0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
0200: 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69 6e  ompiled as a sin
0210: 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74 69  gle.** translati
0220: 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20 54  on unit..**.** T
0230: 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c 20  his file is all 
0240: 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d 70  you need to comp
0250: 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f 20  ile SQLite.  To 
0260: 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f 74  use SQLite in ot
0270: 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73 2c  her.** programs,
0280: 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20 66   you need this f
0290: 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71 6c  ile and the "sql
02a0: 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20 66  ite3.h" header f
02b0: 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65 73  ile that defines
02c0: 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d 6d  .** the programm
02d0: 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ing interface to
02e0: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
02f0: 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64 6f  ary.  (If you do
0300: 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20 74 68 65   not have.** the
0310: 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68 65 61   "sqlite3.h" hea
0320: 64 65 72 20 66 69 6c 65 20 61 74 20 68 61 6e 64  der file at hand
0330: 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e 64 20  , you will find 
0340: 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65 64 20  a copy embedded 
0350: 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 74 65  within.** the te
0360: 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c 65 2e  xt of this file.
0370: 20 20 53 65 61 72 63 68 20 66 6f 72 20 22 42 65    Search for "Be
0380: 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 33  gin file sqlite3
0390: 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68 65 20  .h" to find the 
03a0: 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65 20  start.** of the 
03b0: 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74 65 33  embedded sqlite3
03c0: 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65 2e 29  .h header file.)
03d0: 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f 64 65   Additional code
03e0: 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20 6e 65   files may be ne
03f0: 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75 20 77  eded.** if you w
0400: 61 6e 74 20 61 20 77 72 61 70 70 65 72 20 74 6f  ant a wrapper to
0410: 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c 69 74   interface SQLit
0420: 65 20 77 69 74 68 20 79 6f 75 72 20 63 68 6f 69  e with your choi
0430: 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d 69 6e  ce of programmin
0440: 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e 20 54  g.** language. T
0450: 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68 65 20  he code for the 
0460: 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d 61 6e  "sqlite3" comman
0470: 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69 73 20  d-line shell is 
0480: 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73 65 70  also in a.** sep
0490: 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68 69 73  arate file. This
04a0: 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 6f   file contains o
04b0: 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74 68 65  nly code for the
04c0: 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c 69 62   core SQLite lib
04d0: 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  rary..*/.#define
04e0: 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31 0a 23   SQLITE_CORE 1.#
04f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4d  define SQLITE_AM
0500: 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23 69 66  ALGAMATION 1.#if
0510: 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52 49 56  ndef SQLITE_PRIV
0520: 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  ATE.# define SQL
0530: 49 54 45 5f 50 52 49 56 41 54 45 20 73 74 61 74  ITE_PRIVATE stat
0540: 69 63 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a  ic.#endif./*****
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20  ********* Begin 
0560: 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68  file sqliteInt.h
0570: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0590: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20  ********/./*.** 
05a0: 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31  2001 September 1
05b0: 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  5.**.** The auth
05c0: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70  or disclaims cop
05d0: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73  yright to this s
05e0: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20  ource code.  In 
05f0: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65  place of.** a le
0600: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65  gal notice, here
0610: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a   is a blessing:.
0620: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  **.**    May you
0630: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74   do good and not
0640: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79   evil..**    May
0650: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76   you find forgiv
0660: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65  eness for yourse
0670: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f  lf and forgive o
0680: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79  thers..**    May
0690: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c   you share freel
06a0: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20  y, never taking 
06b0: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69  more than you gi
06c0: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ve..**.*********
06d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
06f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74  .** Internal int
0720: 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f  erface definitio
0730: 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a  ns for SQLite..*
0740: 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  *.*/.#ifndef SQL
0750: 49 54 45 49 4e 54 5f 48 0a 23 64 65 66 69 6e 65  ITEINT_H.#define
0760: 20 53 51 4c 49 54 45 49 4e 54 5f 48 0a 0a 2f 2a   SQLITEINT_H../*
0770: 20 53 70 65 63 69 61 6c 20 43 6f 6d 6d 65 6e 74   Special Comment
0780: 73 3a 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 63 6f  s:.**.** Some co
0790: 6d 6d 65 6e 74 73 20 68 61 76 65 20 73 70 65 63  mments have spec
07a0: 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 74  ial meaning to t
07b0: 68 65 20 74 6f 6f 6c 73 20 74 68 61 74 20 6d 65  he tools that me
07c0: 61 73 75 72 65 20 74 65 73 74 0a 2a 2a 20 63 6f  asure test.** co
07d0: 76 65 72 61 67 65 3a 0a 2a 2a 0a 2a 2a 20 20 20  verage:.**.**   
07e0: 20 4e 4f 5f 54 45 53 54 20 20 20 20 20 20 20 20   NO_TEST        
07f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2d 20 54               - T
0800: 68 65 20 62 72 61 6e 63 68 65 73 20 6f 6e 20 74  he branches on t
0810: 68 69 73 20 6c 69 6e 65 20 61 72 65 20 6e 6f 74  his line are not
0820: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20  .**             
0830: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0840: 20 20 20 20 20 6d 65 61 73 75 72 65 64 20 62 79       measured by
0850: 20 62 72 61 6e 63 68 20 63 6f 76 65 72 61 67 65   branch coverage
0860: 2e 20 20 54 68 69 73 20 69 73 0a 2a 2a 20 20 20  .  This is.**   
0870: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 75                 u
0890: 73 65 64 20 6f 6e 20 6c 69 6e 65 73 20 6f 66 20  sed on lines of 
08a0: 63 6f 64 65 20 74 68 61 74 20 61 63 74 75 61 6c  code that actual
08b0: 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20  ly.**           
08c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
08d0: 20 20 20 20 20 20 20 69 6d 70 6c 65 6d 65 6e 74         implement
08e0: 20 70 61 72 74 73 20 6f 66 20 63 6f 76 65 72 61   parts of covera
08f0: 67 65 20 74 65 73 74 69 6e 67 2e 0a 2a 2a 0a 2a  ge testing..**.*
0900: 2a 20 20 20 20 4f 50 54 49 4d 49 5a 41 54 49 4f  *    OPTIMIZATIO
0910: 4e 2d 49 46 2d 54 52 55 45 20 20 20 20 20 20 20  N-IF-TRUE       
0920: 20 2d 20 54 68 69 73 20 62 72 61 6e 63 68 20 69   - This branch i
0930: 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 61 6c 77  s allowed to alw
0940: 61 79 20 62 65 20 66 61 6c 73 65 0a 2a 2a 20 20  ay be false.**  
0950: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0970: 61 6e 64 20 74 68 65 20 63 6f 72 72 65 63 74 20  and the correct 
0980: 61 6e 73 77 65 72 20 69 73 20 73 74 69 6c 6c 20  answer is still 
0990: 6f 62 74 61 69 6e 65 64 2c 0a 2a 2a 20 20 20 20  obtained,.**    
09a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
09b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 74 68                th
09c0: 6f 75 67 68 20 70 65 72 68 61 70 73 20 6d 6f 72  ough perhaps mor
09d0: 65 20 73 6c 6f 77 6c 79 2e 0a 2a 2a 0a 2a 2a 20  e slowly..**.** 
09e0: 20 20 20 4f 50 54 49 4d 49 5a 41 54 49 4f 4e 2d     OPTIMIZATION-
09f0: 49 46 2d 46 41 4c 53 45 20 20 20 20 20 20 20 2d  IF-FALSE       -
0a00: 20 54 68 69 73 20 62 72 61 6e 63 68 20 69 73 20   This branch is 
0a10: 61 6c 6c 6f 77 65 64 20 74 6f 20 61 6c 77 61 79  allowed to alway
0a20: 20 62 65 20 74 72 75 65 0a 2a 2a 20 20 20 20 20   be true.**     
0a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0a40: 20 20 20 20 20 20 20 20 20 20 20 20 20 61 6e 64               and
0a50: 20 74 68 65 20 63 6f 72 72 65 63 74 20 61 6e 73   the correct ans
0a60: 77 65 72 20 69 73 20 73 74 69 6c 6c 20 6f 62 74  wer is still obt
0a70: 61 69 6e 65 64 2c 0a 2a 2a 20 20 20 20 20 20 20  ained,.**       
0a80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0a90: 20 20 20 20 20 20 20 20 20 20 20 74 68 6f 75 67             thoug
0aa0: 68 20 70 65 72 68 61 70 73 20 6d 6f 72 65 20 73  h perhaps more s
0ab0: 6c 6f 77 6c 79 2e 0a 2a 2a 0a 2a 2a 20 20 20 20  lowly..**.**    
0ac0: 50 52 45 56 45 4e 54 53 2d 48 41 52 4d 4c 45 53  PREVENTS-HARMLES
0ad0: 53 2d 4f 56 45 52 52 45 41 44 20 20 2d 20 54 68  S-OVERREAD  - Th
0ae0: 69 73 20 62 72 61 6e 63 68 20 70 72 65 76 65 6e  is branch preven
0af0: 74 73 20 61 20 62 75 66 66 65 72 20 6f 76 65 72  ts a buffer over
0b00: 72 65 61 64 0a 2a 2a 20 20 20 20 20 20 20 20 20  read.**         
0b10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0b20: 20 20 20 20 20 20 20 20 20 74 68 61 74 20 77 6f           that wo
0b30: 75 6c 64 20 62 65 20 68 61 72 6d 6c 65 73 73 20  uld be harmless 
0b40: 61 6e 64 20 75 6e 64 65 74 65 63 74 61 62 6c 65  and undetectable
0b50: 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 20 20 20  .**             
0b60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
0b70: 20 20 20 20 20 69 66 20 69 74 20 64 69 64 20 6f       if it did o
0b80: 63 63 75 72 2e 20 20 0a 2a 2a 0a 2a 2a 20 49 6e  ccur.  .**.** In
0b90: 20 61 6c 6c 20 63 61 73 65 73 2c 20 74 68 65 20   all cases, the 
0ba0: 73 70 65 63 69 61 6c 20 63 6f 6d 6d 65 6e 74 20  special comment 
0bb0: 6d 75 73 74 20 62 65 20 65 6e 63 6c 6f 73 65 64  must be enclosed
0bc0: 20 69 6e 20 74 68 65 20 75 73 75 61 6c 0a 2a 2a   in the usual.**
0bd0: 20 73 6c 61 73 68 2d 61 73 74 65 72 69 73 6b 2e   slash-asterisk.
0be0: 2e 2e 61 73 74 65 72 69 73 6b 2d 73 6c 61 73 68  ..asterisk-slash
0bf0: 20 63 6f 6d 6d 65 6e 74 20 6d 61 72 6b 73 2c 20   comment marks, 
0c00: 77 69 74 68 20 6e 6f 20 73 70 61 63 65 73 20 62  with no spaces b
0c10: 65 74 77 65 65 6e 20 74 68 65 20 0a 2a 2a 20 61  etween the .** a
0c20: 73 74 65 72 69 73 6b 73 20 61 6e 64 20 74 68 65  sterisks and the
0c30: 20 63 6f 6d 6d 65 6e 74 20 74 65 78 74 2e 0a 2a   comment text..*
0c40: 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75  /../*.** Make su
0c50: 72 65 20 74 68 65 20 54 63 6c 20 63 61 6c 6c 69  re the Tcl calli
0c60: 6e 67 20 63 6f 6e 76 65 6e 74 69 6f 6e 20 6d 61  ng convention ma
0c70: 63 72 6f 20 69 73 20 64 65 66 69 6e 65 64 2e 20  cro is defined. 
0c80: 20 54 68 69 73 20 6d 61 63 72 6f 20 69 73 0a 2a   This macro is.*
0c90: 2a 20 6f 6e 6c 79 20 75 73 65 64 20 62 79 20 74  * only used by t
0ca0: 65 73 74 20 63 6f 64 65 20 61 6e 64 20 54 63 6c  est code and Tcl
0cb0: 20 69 6e 74 65 67 72 61 74 69 6f 6e 20 63 6f 64   integration cod
0cc0: 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  e..*/.#ifndef SQ
0cd0: 4c 49 54 45 5f 54 43 4c 41 50 49 0a 23 20 20 64  LITE_TCLAPI.#  d
0ce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 43 4c  efine SQLITE_TCL
0cf0: 41 50 49 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  API.#endif../*.*
0d00: 2a 20 4d 61 6b 65 20 73 75 72 65 20 74 68 61 74  * Make sure that
0d10: 20 72 61 6e 64 5f 73 28 29 20 69 73 20 61 76 61   rand_s() is ava
0d20: 69 6c 61 62 6c 65 20 6f 6e 20 57 69 6e 64 6f 77  ilable on Window
0d30: 73 20 73 79 73 74 65 6d 73 20 77 69 74 68 20 4d  s systems with M
0d40: 53 56 43 20 32 30 30 35 0a 2a 2a 20 6f 72 20 68  SVC 2005.** or h
0d50: 69 67 68 65 72 2e 0a 2a 2f 0a 23 69 66 20 64 65  igher..*/.#if de
0d60: 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20  fined(_MSC_VER) 
0d70: 26 26 20 5f 4d 53 43 5f 56 45 52 3e 3d 31 34 30  && _MSC_VER>=140
0d80: 30 0a 23 20 20 64 65 66 69 6e 65 20 5f 43 52 54  0.#  define _CRT
0d90: 5f 52 41 4e 44 5f 53 0a 23 65 6e 64 69 66 0a 0a  _RAND_S.#endif..
0da0: 2f 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68  /*.** Include th
0db0: 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 75 73  e header file us
0dc0: 65 64 20 74 6f 20 63 75 73 74 6f 6d 69 7a 65 20  ed to customize 
0dd0: 74 68 65 20 63 6f 6d 70 69 6c 65 72 20 6f 70 74  the compiler opt
0de0: 69 6f 6e 73 20 66 6f 72 20 4d 53 56 43 2e 0a 2a  ions for MSVC..*
0df0: 2a 20 54 68 69 73 20 73 68 6f 75 6c 64 20 62 65  * This should be
0e00: 20 64 6f 6e 65 20 66 69 72 73 74 20 73 6f 20 74   done first so t
0e10: 68 61 74 20 69 74 20 63 61 6e 20 73 75 63 63 65  hat it can succe
0e20: 73 73 66 75 6c 6c 79 20 70 72 65 76 65 6e 74 20  ssfully prevent 
0e30: 73 70 75 72 69 6f 75 73 0a 2a 2a 20 63 6f 6d 70  spurious.** comp
0e40: 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 20 64 75  iler warnings du
0e50: 65 20 74 6f 20 73 75 62 73 65 71 75 65 6e 74 20  e to subsequent 
0e60: 63 6f 6e 74 65 6e 74 20 69 6e 20 74 68 69 73 20  content in this 
0e70: 66 69 6c 65 20 61 6e 64 20 6f 74 68 65 72 20 66  file and other f
0e80: 69 6c 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  iles.** that are
0e90: 20 69 6e 63 6c 75 64 65 64 20 62 79 20 74 68 69   included by thi
0ea0: 73 20 66 69 6c 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a  s file..*/./****
0eb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75  ********** Inclu
0ec0: 64 65 20 6d 73 76 63 2e 68 20 69 6e 20 74 68 65  de msvc.h in the
0ed0: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74   middle of sqlit
0ee0: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
0ef0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a  *********/./****
0f00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e  ********** Begin
0f10: 20 66 69 6c 65 20 6d 73 76 63 2e 68 20 2a 2a 2a   file msvc.h ***
0f20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0f30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0f40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a  *********/./*.**
0f50: 20 32 30 31 35 20 4a 61 6e 75 61 72 79 20 31 32   2015 January 12
0f60: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
0f70: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
0f80: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
0f90: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
0fa0: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
0fb0: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
0fc0: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
0fd0: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
0fe0: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
0ff0: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
1000: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
1010: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
1020: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
1030: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
1040: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
1050: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
1060: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
1070: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
1080: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1090: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
10a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
10b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
10c0: 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ****.**.** This 
10d0: 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 63 6f  file contains co
10e0: 64 65 20 74 68 61 74 20 69 73 20 73 70 65 63 69  de that is speci
10f0: 66 69 63 20 74 6f 20 4d 53 56 43 2e 0a 2a 2f 0a  fic to MSVC..*/.
1100: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  #ifndef SQLITE_M
1110: 53 56 43 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  SVC_H.#define SQ
1120: 4c 49 54 45 5f 4d 53 56 43 5f 48 0a 0a 23 69 66  LITE_MSVC_H..#if
1130: 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45   defined(_MSC_VE
1140: 52 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  R).#pragma warni
1150: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 30 35  ng(disable : 405
1160: 34 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  4).#pragma warni
1170: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 30 35  ng(disable : 405
1180: 35 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  5).#pragma warni
1190: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 30  ng(disable : 410
11a0: 30 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  0).#pragma warni
11b0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 32  ng(disable : 412
11c0: 37 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  7).#pragma warni
11d0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 33  ng(disable : 413
11e0: 30 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  0).#pragma warni
11f0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 35  ng(disable : 415
1200: 32 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  2).#pragma warni
1210: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 31 38  ng(disable : 418
1220: 39 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  9).#pragma warni
1230: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 30  ng(disable : 420
1240: 36 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  6).#pragma warni
1250: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 31  ng(disable : 421
1260: 30 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  0).#pragma warni
1270: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 33  ng(disable : 423
1280: 32 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  2).#pragma warni
1290: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 32 34  ng(disable : 424
12a0: 34 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  4).#pragma warni
12b0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 33 30  ng(disable : 430
12c0: 35 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  5).#pragma warni
12d0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 33 30  ng(disable : 430
12e0: 36 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  6).#pragma warni
12f0: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 37 30  ng(disable : 470
1300: 32 29 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 69  2).#pragma warni
1310: 6e 67 28 64 69 73 61 62 6c 65 20 3a 20 34 37 30  ng(disable : 470
1320: 36 29 0a 23 65 6e 64 69 66 20 2f 2a 20 64 65 66  6).#endif /* def
1330: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 2a  ined(_MSC_VER) *
1340: 2f 0a 0a 23 65 6e 64 69 66 20 2f 2a 20 53 51 4c  /..#endif /* SQL
1350: 49 54 45 5f 4d 53 56 43 5f 48 20 2a 2f 0a 0a 2f  ITE_MSVC_H */../
1360: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45  ************** E
1370: 6e 64 20 6f 66 20 6d 73 76 63 2e 68 20 2a 2a 2a  nd of msvc.h ***
1380: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1390: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
13a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
13b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43  ************** C
13c0: 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72 65 20  ontinuing where 
13d0: 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e 20 73  we left off in s
13e0: 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a  qliteInt.h *****
13f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a  *************/..
1400: 2f 2a 0a 2a 2a 20 53 70 65 63 69 61 6c 20 73 65  /*.** Special se
1410: 74 75 70 20 66 6f 72 20 56 78 57 6f 72 6b 73 0a  tup for VxWorks.
1420: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
1430: 2a 2a 20 49 6e 63 6c 75 64 65 20 76 78 77 6f 72  ** Include vxwor
1440: 6b 73 2e 68 20 69 6e 20 74 68 65 20 6d 69 64 64  ks.h in the midd
1450: 6c 65 20 6f 66 20 73 71 6c 69 74 65 49 6e 74 2e  le of sqliteInt.
1460: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  h **************
1470: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
1480: 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 76 78  ** Begin file vx
1490: 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a  works.h ********
14a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
14b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
14c0: 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 31 35 2d 30 33  */./*.** 2015-03
14d0: 2d 30 32 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  -02.**.** The au
14e0: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
14f0: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
1500: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
1510: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
1520: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
1530: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
1540: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
1550: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
1560: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
1570: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
1580: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
1590: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
15a0: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
15b0: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
15c0: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
15d0: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
15e0: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
15f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1600: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1630: 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a 20 54 68  *******.**.** Th
1640: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
1650: 20 63 6f 64 65 20 74 68 61 74 20 69 73 20 73 70   code that is sp
1660: 65 63 69 66 69 63 20 74 6f 20 57 69 6e 64 20 52  ecific to Wind R
1670: 69 76 65 72 27 73 20 56 78 57 6f 72 6b 73 0a 2a  iver's VxWorks.*
1680: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f  /.#if defined(__
1690: 52 54 50 5f 5f 29 20 7c 7c 20 64 65 66 69 6e 65  RTP__) || define
16a0: 64 28 5f 57 52 53 5f 4b 45 52 4e 45 4c 29 0a 2f  d(_WRS_KERNEL)./
16b0: 2a 20 54 68 69 73 20 69 73 20 56 78 57 6f 72 6b  * This is VxWork
16c0: 73 2e 20 20 53 65 74 20 75 70 20 74 68 69 6e 67  s.  Set up thing
16d0: 73 20 73 70 65 63 69 61 6c 6c 79 20 66 6f 72 20  s specially for 
16e0: 74 68 61 74 20 4f 53 0a 2a 2f 0a 23 69 6e 63 6c  that OS.*/.#incl
16f0: 75 64 65 20 3c 76 78 57 6f 72 6b 73 2e 68 3e 0a  ude <vxWorks.h>.
1700: 23 69 6e 63 6c 75 64 65 20 3c 70 74 68 72 65 61  #include <pthrea
1710: 64 2e 68 3e 20 20 2f 2a 20 61 6d 61 6c 67 61 6d  d.h>  /* amalgam
1720: 61 74 6f 72 3a 20 64 6f 6e 74 63 61 63 68 65 20  ator: dontcache 
1730: 2a 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f 56 58  */.#define OS_VX
1740: 57 4f 52 4b 53 20 31 0a 23 64 65 66 69 6e 65 20  WORKS 1.#define 
1750: 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 20  SQLITE_OS_OTHER 
1760: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
1770: 5f 48 4f 4d 45 47 52 4f 57 4e 5f 52 45 43 55 52  _HOMEGROWN_RECUR
1780: 53 49 56 45 5f 4d 55 54 45 58 20 31 0a 23 64 65  SIVE_MUTEX 1.#de
1790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fine SQLITE_OMIT
17a0: 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 20  _LOAD_EXTENSION 
17b0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
17c0: 5f 45 4e 41 42 4c 45 5f 4c 4f 43 4b 49 4e 47 5f  _ENABLE_LOCKING_
17d0: 53 54 59 4c 45 20 30 0a 23 64 65 66 69 6e 65 20  STYLE 0.#define 
17e0: 48 41 56 45 5f 55 54 49 4d 45 20 31 0a 23 65 6c  HAVE_UTIME 1.#el
17f0: 73 65 0a 2f 2a 20 54 68 69 73 20 69 73 20 6e 6f  se./* This is no
1800: 74 20 56 78 57 6f 72 6b 73 2e 20 2a 2f 0a 23 64  t VxWorks. */.#d
1810: 65 66 69 6e 65 20 4f 53 5f 56 58 57 4f 52 4b 53  efine OS_VXWORKS
1820: 20 30 0a 23 64 65 66 69 6e 65 20 48 41 56 45 5f   0.#define HAVE_
1830: 46 43 48 4f 57 4e 20 31 0a 23 64 65 66 69 6e 65  FCHOWN 1.#define
1840: 20 48 41 56 45 5f 52 45 41 44 4c 49 4e 4b 20 31   HAVE_READLINK 1
1850: 0a 23 64 65 66 69 6e 65 20 48 41 56 45 5f 4c 53  .#define HAVE_LS
1860: 54 41 54 20 31 0a 23 65 6e 64 69 66 20 2f 2a 20  TAT 1.#endif /* 
1870: 64 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45 52  defined(_WRS_KER
1880: 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a  NEL) */../******
1890: 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64 20 6f 66 20  ******** End of 
18a0: 76 78 77 6f 72 6b 73 2e 68 20 2a 2a 2a 2a 2a 2a  vxworks.h ******
18b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
18d0: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  *******/./******
18e0: 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e 74 69 6e 75  ******** Continu
18f0: 69 6e 67 20 77 68 65 72 65 20 77 65 20 6c 65 66  ing where we lef
1900: 74 20 6f 66 66 20 69 6e 20 73 71 6c 69 74 65 49  t off in sqliteI
1910: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  nt.h ***********
1920: 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  *******/../*.** 
1930: 54 68 65 73 65 20 23 64 65 66 69 6e 65 73 20 73  These #defines s
1940: 68 6f 75 6c 64 20 65 6e 61 62 6c 65 20 3e 32 47  hould enable >2G
1950: 42 20 66 69 6c 65 20 73 75 70 70 6f 72 74 20 6f  B file support o
1960: 6e 20 50 4f 53 49 58 20 69 66 20 74 68 65 0a 2a  n POSIX if the.*
1970: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65  * underlying ope
1980: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 73 75  rating system su
1990: 70 70 6f 72 74 73 20 69 74 2e 20 20 49 66 20 74  pports it.  If t
19a0: 68 65 20 4f 53 20 6c 61 63 6b 73 0a 2a 2a 20 6c  he OS lacks.** l
19b0: 61 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72  arge file suppor
19c0: 74 2c 20 6f 72 20 69 66 20 74 68 65 20 4f 53 20  t, or if the OS 
19d0: 69 73 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 73  is windows, thes
19e0: 65 20 73 68 6f 75 6c 64 20 62 65 20 6e 6f 2d 6f  e should be no-o
19f0: 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 69 63 6b 65 74  ps..**.** Ticket
1a00: 20 23 32 37 33 39 3a 20 20 54 68 65 20 5f 4c 41   #2739:  The _LA
1a10: 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 20 6d  RGEFILE_SOURCE m
1a20: 61 63 72 6f 20 6d 75 73 74 20 61 70 70 65 61 72  acro must appear
1a30: 20 62 65 66 6f 72 65 20 61 6e 79 0a 2a 2a 20 73   before any.** s
1a40: 79 73 74 65 6d 20 23 69 6e 63 6c 75 64 65 73 2e  ystem #includes.
1a50: 20 20 48 65 6e 63 65 2c 20 74 68 69 73 20 62 6c    Hence, this bl
1a60: 6f 63 6b 20 6f 66 20 63 6f 64 65 20 6d 75 73 74  ock of code must
1a70: 20 62 65 20 74 68 65 20 76 65 72 79 20 66 69 72   be the very fir
1a80: 73 74 0a 2a 2a 20 63 6f 64 65 20 69 6e 20 61 6c  st.** code in al
1a90: 6c 20 73 6f 75 72 63 65 20 66 69 6c 65 73 2e 0a  l source files..
1aa0: 2a 2a 0a 2a 2a 20 4c 61 72 67 65 20 66 69 6c 65  **.** Large file
1ab0: 20 73 75 70 70 6f 72 74 20 63 61 6e 20 62 65 20   support can be 
1ac0: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 74  disabled using t
1ad0: 68 65 20 2d 44 53 51 4c 49 54 45 5f 44 49 53 41  he -DSQLITE_DISA
1ae0: 42 4c 45 5f 4c 46 53 20 73 77 69 74 63 68 0a 2a  BLE_LFS switch.*
1af0: 2a 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  * on the compile
1b00: 72 20 63 6f 6d 6d 61 6e 64 20 6c 69 6e 65 2e 20  r command line. 
1b10: 20 54 68 69 73 20 69 73 20 6e 65 63 65 73 73 61   This is necessa
1b20: 72 79 20 69 66 20 79 6f 75 20 61 72 65 20 63 6f  ry if you are co
1b30: 6d 70 69 6c 69 6e 67 0a 2a 2a 20 6f 6e 20 61 20  mpiling.** on a 
1b40: 72 65 63 65 6e 74 20 6d 61 63 68 69 6e 65 20 28  recent machine (
1b50: 65 78 3a 20 52 65 64 20 48 61 74 20 37 2e 32 29  ex: Red Hat 7.2)
1b60: 20 62 75 74 20 79 6f 75 20 77 61 6e 74 20 79 6f   but you want yo
1b70: 75 72 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a  ur code to work.
1b80: 2a 2a 20 6f 6e 20 61 6e 20 6f 6c 64 65 72 20 6d  ** on an older m
1b90: 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20  achine (ex: Red 
1ba0: 48 61 74 20 36 2e 30 29 2e 20 20 49 66 20 79 6f  Hat 6.0).  If yo
1bb0: 75 20 63 6f 6d 70 69 6c 65 20 6f 6e 20 52 65 64  u compile on Red
1bc0: 20 48 61 74 20 37 2e 32 0a 2a 2a 20 77 69 74 68   Hat 7.2.** with
1bd0: 6f 75 74 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c  out this option,
1be0: 20 4c 46 53 20 69 73 20 65 6e 61 62 6c 65 2e 20   LFS is enable. 
1bf0: 20 42 75 74 20 4c 46 53 20 64 6f 65 73 20 6e 6f   But LFS does no
1c00: 74 20 65 78 69 73 74 20 69 6e 20 74 68 65 20 6b  t exist in the k
1c10: 65 72 6e 65 6c 0a 2a 2a 20 69 6e 20 52 65 64 20  ernel.** in Red 
1c20: 48 61 74 20 36 2e 30 2c 20 73 6f 20 74 68 65 20  Hat 6.0, so the 
1c30: 63 6f 64 65 20 77 6f 6e 27 74 20 77 6f 72 6b 2e  code won't work.
1c40: 20 20 48 65 6e 63 65 2c 20 66 6f 72 20 6d 61 78    Hence, for max
1c50: 69 6d 75 6d 20 62 69 6e 61 72 79 0a 2a 2a 20 70  imum binary.** p
1c60: 6f 72 74 61 62 69 6c 69 74 79 20 79 6f 75 20 73  ortability you s
1c70: 68 6f 75 6c 64 20 6f 6d 69 74 20 4c 46 53 2e 0a  hould omit LFS..
1c80: 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 76 69 6f  **.** The previo
1c90: 75 73 20 70 61 72 61 67 72 61 70 68 20 77 61 73  us paragraph was
1ca0: 20 77 72 69 74 74 65 6e 20 69 6e 20 32 30 30 35   written in 2005
1cb0: 2e 20 20 28 54 68 69 73 20 70 61 72 61 67 72 61  .  (This paragra
1cc0: 70 68 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  ph is written.**
1cd0: 20 6f 6e 20 32 30 30 38 2d 31 31 2d 32 38 2e 29   on 2008-11-28.)
1ce0: 20 54 68 65 73 65 20 64 61 79 73 2c 20 61 6c 6c   These days, all
1cf0: 20 4c 69 6e 75 78 20 6b 65 72 6e 65 6c 73 20 73   Linux kernels s
1d00: 75 70 70 6f 72 74 20 6c 61 72 67 65 20 66 69 6c  upport large fil
1d10: 65 73 2c 20 73 6f 0a 2a 2a 20 79 6f 75 20 73 68  es, so.** you sh
1d20: 6f 75 6c 64 20 70 72 6f 62 61 62 6c 79 20 6c 65  ould probably le
1d30: 61 76 65 20 4c 46 53 20 65 6e 61 62 6c 65 64 2e  ave LFS enabled.
1d40: 20 20 42 75 74 20 73 6f 6d 65 20 65 6d 62 65 64    But some embed
1d50: 64 65 64 20 70 6c 61 74 66 6f 72 6d 73 20 6d 69  ded platforms mi
1d60: 67 68 74 0a 2a 2a 20 6c 61 63 6b 20 4c 46 53 20  ght.** lack LFS 
1d70: 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
1d80: 65 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45  e SQLITE_DISABLE
1d90: 5f 4c 46 53 20 6d 61 63 72 6f 20 6d 69 67 68 74  _LFS macro might
1da0: 20 73 74 69 6c 6c 20 62 65 20 75 73 65 66 75 6c   still be useful
1db0: 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d 69 6c 61 72 20  ..**.** Similar 
1dc0: 69 73 20 74 72 75 65 20 66 6f 72 20 4d 61 63 20  is true for Mac 
1dd0: 4f 53 20 58 2e 20 20 4c 46 53 20 69 73 20 6f 6e  OS X.  LFS is on
1de0: 6c 79 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20  ly supported on 
1df0: 4d 61 63 20 4f 53 20 58 20 39 20 61 6e 64 20 6c  Mac OS X 9 and l
1e00: 61 74 65 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  ater..*/.#ifndef
1e10: 20 53 51 4c 49 54 45 5f 44 49 53 41 42 4c 45 5f   SQLITE_DISABLE_
1e20: 4c 46 53 0a 23 20 64 65 66 69 6e 65 20 5f 4c 41  LFS.# define _LA
1e30: 52 47 45 5f 46 49 4c 45 20 20 20 20 20 20 20 31  RGE_FILE       1
1e40: 0a 23 20 69 66 6e 64 65 66 20 5f 46 49 4c 45 5f  .# ifndef _FILE_
1e50: 4f 46 46 53 45 54 5f 42 49 54 53 0a 23 20 20 20  OFFSET_BITS.#   
1e60: 64 65 66 69 6e 65 20 5f 46 49 4c 45 5f 4f 46 46  define _FILE_OFF
1e70: 53 45 54 5f 42 49 54 53 20 36 34 0a 23 20 65 6e  SET_BITS 64.# en
1e80: 64 69 66 0a 23 20 64 65 66 69 6e 65 20 5f 4c 41  dif.# define _LA
1e90: 52 47 45 46 49 4c 45 5f 53 4f 55 52 43 45 20 31  RGEFILE_SOURCE 1
1ea0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 54 68 65 20  .#endif../* The 
1eb0: 47 43 43 5f 56 45 52 53 49 4f 4e 20 61 6e 64 20  GCC_VERSION and 
1ec0: 4d 53 56 43 5f 56 45 52 53 49 4f 4e 20 6d 61 63  MSVC_VERSION mac
1ed0: 72 6f 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  ros are used to.
1ee0: 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 61 6c 6c 79  ** conditionally
1ef0: 20 69 6e 63 6c 75 64 65 20 6f 70 74 69 6d 69 7a   include optimiz
1f00: 61 74 69 6f 6e 73 20 66 6f 72 20 65 61 63 68 20  ations for each 
1f10: 6f 66 20 74 68 65 73 65 20 63 6f 6d 70 69 6c 65  of these compile
1f20: 72 73 2e 20 20 41 0a 2a 2a 20 76 61 6c 75 65 20  rs.  A.** value 
1f30: 6f 66 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20  of 0 means that 
1f40: 63 6f 6d 70 69 6c 65 72 20 69 73 20 6e 6f 74 20  compiler is not 
1f50: 62 65 69 6e 67 20 75 73 65 64 2e 20 20 54 68 65  being used.  The
1f60: 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 49 53 41 42  .** SQLITE_DISAB
1f70: 4c 45 5f 49 4e 54 52 49 4e 53 49 43 20 6d 61 63  LE_INTRINSIC mac
1f80: 72 6f 20 6d 65 61 6e 73 20 64 6f 20 6e 6f 74 20  ro means do not 
1f90: 75 73 65 20 61 6e 79 20 63 6f 6d 70 69 6c 65 72  use any compiler
1fa0: 2d 73 70 65 63 69 66 69 63 0a 2a 2a 20 6f 70 74  -specific.** opt
1fb0: 69 6d 69 7a 61 74 69 6f 6e 73 2c 20 61 6e 64 20  imizations, and 
1fc0: 68 65 6e 63 65 20 73 65 74 20 61 6c 6c 20 63 6f  hence set all co
1fd0: 6d 70 69 6c 65 72 20 6d 61 63 72 6f 73 20 74 6f  mpiler macros to
1fe0: 20 30 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 77   0.**.** There w
1ff0: 61 73 20 6f 6e 63 65 20 61 6c 73 6f 20 61 20 43  as once also a C
2000: 4c 41 4e 47 5f 56 45 52 53 49 4f 4e 20 6d 61 63  LANG_VERSION mac
2010: 72 6f 2e 20 20 48 6f 77 65 76 65 72 2c 20 77 65  ro.  However, we
2020: 20 6c 65 61 72 6e 20 74 68 61 74 20 74 68 65 0a   learn that the.
2030: 2a 2a 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  ** version numbe
2040: 72 73 20 69 6e 20 63 6c 61 6e 67 20 61 72 65 20  rs in clang are 
2050: 66 6f 72 20 22 6d 61 72 6b 65 74 69 6e 67 22 20  for "marketing" 
2060: 6f 6e 6c 79 20 61 6e 64 20 61 72 65 20 69 6e 63  only and are inc
2070: 6f 6e 73 69 73 74 65 6e 74 0a 2a 2a 20 61 6e 64  onsistent.** and
2080: 20 75 6e 72 65 6c 69 61 62 6c 65 2e 20 20 46 6f   unreliable.  Fo
2090: 72 74 75 6e 61 74 65 6c 79 2c 20 61 6c 6c 20 76  rtunately, all v
20a0: 65 72 73 69 6f 6e 73 20 6f 66 20 63 6c 61 6e 67  ersions of clang
20b0: 20 61 6c 73 6f 20 72 65 63 6f 67 6e 69 7a 65 20   also recognize 
20c0: 74 68 65 0a 2a 2a 20 67 63 63 20 76 65 72 73 69  the.** gcc versi
20d0: 6f 6e 20 6e 75 6d 62 65 72 73 20 61 6e 64 20 68  on numbers and h
20e0: 61 76 65 20 72 65 61 73 6f 6e 61 62 6c 65 20 73  ave reasonable s
20f0: 65 74 74 69 6e 67 73 20 66 6f 72 20 67 63 63 20  ettings for gcc 
2100: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 73 2c  version numbers,
2110: 0a 2a 2a 20 73 6f 20 74 68 65 20 47 43 43 5f 56  .** so the GCC_V
2120: 45 52 53 49 4f 4e 20 6d 61 63 72 6f 20 77 69 6c  ERSION macro wil
2130: 6c 20 62 65 20 73 65 74 20 74 6f 20 61 20 63 6f  l be set to a co
2140: 72 72 65 63 74 20 6e 6f 6e 2d 7a 65 72 6f 20 76  rrect non-zero v
2150: 61 6c 75 65 20 65 76 65 6e 0a 2a 2a 20 77 68 65  alue even.** whe
2160: 6e 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68  n compiling with
2170: 20 63 6c 61 6e 67 2e 0a 2a 2f 0a 23 69 66 20 64   clang..*/.#if d
2180: 65 66 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f 29  efined(__GNUC__)
2190: 20 26 26 20 21 64 65 66 69 6e 65 64 28 53 51 4c   && !defined(SQL
21a0: 49 54 45 5f 44 49 53 41 42 4c 45 5f 49 4e 54 52  ITE_DISABLE_INTR
21b0: 49 4e 53 49 43 29 0a 23 20 64 65 66 69 6e 65 20  INSIC).# define 
21c0: 47 43 43 5f 56 45 52 53 49 4f 4e 20 28 5f 5f 47  GCC_VERSION (__G
21d0: 4e 55 43 5f 5f 2a 31 30 30 30 30 30 30 2b 5f 5f  NUC__*1000000+__
21e0: 47 4e 55 43 5f 4d 49 4e 4f 52 5f 5f 2a 31 30 30  GNUC_MINOR__*100
21f0: 30 2b 5f 5f 47 4e 55 43 5f 50 41 54 43 48 4c 45  0+__GNUC_PATCHLE
2200: 56 45 4c 5f 5f 29 0a 23 65 6c 73 65 0a 23 20 64  VEL__).#else.# d
2210: 65 66 69 6e 65 20 47 43 43 5f 56 45 52 53 49 4f  efine GCC_VERSIO
2220: 4e 20 30 0a 23 65 6e 64 69 66 0a 23 69 66 20 64  N 0.#endif.#if d
2230: 65 66 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29  efined(_MSC_VER)
2240: 20 26 26 20 21 64 65 66 69 6e 65 64 28 53 51 4c   && !defined(SQL
2250: 49 54 45 5f 44 49 53 41 42 4c 45 5f 49 4e 54 52  ITE_DISABLE_INTR
2260: 49 4e 53 49 43 29 0a 23 20 64 65 66 69 6e 65 20  INSIC).# define 
2270: 4d 53 56 43 5f 56 45 52 53 49 4f 4e 20 5f 4d 53  MSVC_VERSION _MS
2280: 43 5f 56 45 52 0a 23 65 6c 73 65 0a 23 20 64 65  C_VER.#else.# de
2290: 66 69 6e 65 20 4d 53 56 43 5f 56 45 52 53 49 4f  fine MSVC_VERSIO
22a0: 4e 20 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 4e  N 0.#endif../* N
22b0: 65 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f 75  eeded for variou
22c0: 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e 2e  s definitions...
22d0: 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28   */.#if defined(
22e0: 5f 5f 47 4e 55 43 5f 5f 29 20 26 26 20 21 64 65  __GNUC__) && !de
22f0: 66 69 6e 65 64 28 5f 47 4e 55 5f 53 4f 55 52 43  fined(_GNU_SOURC
2300: 45 29 0a 23 20 64 65 66 69 6e 65 20 5f 47 4e 55  E).# define _GNU
2310: 5f 53 4f 55 52 43 45 0a 23 65 6e 64 69 66 0a 0a  _SOURCE.#endif..
2320: 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 4f 70  #if defined(__Op
2330: 65 6e 42 53 44 5f 5f 29 20 26 26 20 21 64 65 66  enBSD__) && !def
2340: 69 6e 65 64 28 5f 42 53 44 5f 53 4f 55 52 43 45  ined(_BSD_SOURCE
2350: 29 0a 23 20 64 65 66 69 6e 65 20 5f 42 53 44 5f  ).# define _BSD_
2360: 53 4f 55 52 43 45 0a 23 65 6e 64 69 66 0a 0a 2f  SOURCE.#endif../
2370: 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47 57 2c 20  *.** For MinGW, 
2380: 63 68 65 63 6b 20 74 6f 20 73 65 65 20 69 66 20  check to see if 
2390: 77 65 20 63 61 6e 20 69 6e 63 6c 75 64 65 20 74  we can include t
23a0: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20 63  he header file c
23b0: 6f 6e 74 61 69 6e 69 6e 67 20 69 74 73 0a 2a 2a  ontaining its.**
23c0: 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d 61   version informa
23d0: 74 69 6f 6e 2c 20 61 6d 6f 6e 67 20 6f 74 68 65  tion, among othe
23e0: 72 20 74 68 69 6e 67 73 2e 20 20 4e 6f 72 6d 61  r things.  Norma
23f0: 6c 6c 79 2c 20 74 68 69 73 20 69 6e 74 65 72 6e  lly, this intern
2400: 61 6c 20 4d 69 6e 47 57 0a 2a 2a 20 68 65 61 64  al MinGW.** head
2410: 65 72 20 66 69 6c 65 20 77 6f 75 6c 64 20 5b 6f  er file would [o
2420: 6e 6c 79 5d 20 62 65 20 69 6e 63 6c 75 64 65 64  nly] be included
2430: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
2440: 79 20 6f 74 68 65 72 20 4d 69 6e 47 57 20 68 65  y other MinGW he
2450: 61 64 65 72 0a 2a 2a 20 66 69 6c 65 73 3b 20 68  ader.** files; h
2460: 6f 77 65 76 65 72 2c 20 74 68 65 20 63 6f 6e 74  owever, the cont
2470: 61 69 6e 65 64 20 76 65 72 73 69 6f 6e 20 69 6e  ained version in
2480: 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6e 6f 77  formation is now
2490: 20 72 65 71 75 69 72 65 64 20 62 79 20 74 68 69   required by thi
24a0: 73 0a 2a 2a 20 68 65 61 64 65 72 20 66 69 6c 65  s.** header file
24b0: 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
24c0: 62 69 6e 61 72 79 20 63 6f 6d 70 61 74 69 62 69  binary compatibi
24d0: 6c 69 74 79 20 69 73 73 75 65 73 20 28 73 65 65  lity issues (see
24e0: 20 62 65 6c 6f 77 29 20 61 6e 64 0a 2a 2a 20 74   below) and.** t
24f0: 68 69 73 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  his is the only 
2500: 6b 6e 6f 77 6e 20 77 61 79 20 74 6f 20 72 65 6c  known way to rel
2510: 69 61 62 6c 79 20 6f 62 74 61 69 6e 20 69 74 2e  iably obtain it.
2520: 20 20 54 68 69 73 20 65 6e 74 69 72 65 20 23 69    This entire #i
2530: 66 20 62 6c 6f 63 6b 0a 2a 2a 20 77 6f 75 6c 64  f block.** would
2540: 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 20 75   be completely u
2550: 6e 6e 65 63 65 73 73 61 72 79 20 69 66 20 74 68  nnecessary if th
2560: 65 72 65 20 77 61 73 20 61 6e 79 20 6f 74 68 65  ere was any othe
2570: 72 20 77 61 79 20 6f 66 20 64 65 74 65 63 74 69  r way of detecti
2580: 6e 67 0a 2a 2a 20 4d 69 6e 47 57 20 76 69 61 20  ng.** MinGW via 
2590: 74 68 65 69 72 20 70 72 65 70 72 6f 63 65 73 73  their preprocess
25a0: 6f 72 20 28 65 2e 67 2e 20 69 66 20 74 68 65 79  or (e.g. if they
25b0: 20 63 75 73 74 6f 6d 69 7a 65 64 20 74 68 65 69   customized thei
25c0: 72 20 47 43 43 20 74 6f 20 64 65 66 69 6e 65 0a  r GCC to define.
25d0: 2a 2a 20 73 6f 6d 65 20 4d 69 6e 47 57 2d 73 70  ** some MinGW-sp
25e0: 65 63 69 66 69 63 20 6d 61 63 72 6f 73 29 2e 20  ecific macros). 
25f0: 20 57 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67 20   When compiling 
2600: 66 6f 72 20 4d 69 6e 47 57 2c 20 65 69 74 68 65  for MinGW, eithe
2610: 72 20 74 68 65 0a 2a 2a 20 5f 48 41 56 45 5f 4d  r the.** _HAVE_M
2620: 49 4e 47 57 5f 48 20 6f 72 20 5f 48 41 56 45 5f  INGW_H or _HAVE_
2630: 5f 4d 49 4e 47 57 5f 48 20 28 6e 6f 74 65 20 74  _MINGW_H (note t
2640: 68 65 20 65 78 74 72 61 20 75 6e 64 65 72 73 63  he extra undersc
2650: 6f 72 65 29 20 6d 61 63 72 6f 20 6d 75 73 74 20  ore) macro must 
2660: 62 65 0a 2a 2a 20 64 65 66 69 6e 65 64 3b 20 6f  be.** defined; o
2670: 74 68 65 72 77 69 73 65 2c 20 64 65 74 65 63 74  therwise, detect
2680: 69 6f 6e 20 6f 66 20 63 6f 6e 64 69 74 69 6f 6e  ion of condition
2690: 73 20 73 70 65 63 69 66 69 63 20 74 6f 20 4d 69  s specific to Mi
26a0: 6e 47 57 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  nGW will be.** d
26b0: 69 73 61 62 6c 65 64 2e 0a 2a 2f 0a 23 69 66 20  isabled..*/.#if 
26c0: 64 65 66 69 6e 65 64 28 5f 48 41 56 45 5f 4d 49  defined(_HAVE_MI
26d0: 4e 47 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65  NGW_H).# include
26e0: 20 22 6d 69 6e 67 77 2e 68 22 0a 23 65 6c 69 66   "mingw.h".#elif
26f0: 20 64 65 66 69 6e 65 64 28 5f 48 41 56 45 5f 5f   defined(_HAVE__
2700: 4d 49 4e 47 57 5f 48 29 0a 23 20 69 6e 63 6c 75  MINGW_H).# inclu
2710: 64 65 20 22 5f 6d 69 6e 67 77 2e 68 22 0a 23 65  de "_mingw.h".#e
2720: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20  ndif../*.** For 
2730: 4d 69 6e 47 57 20 76 65 72 73 69 6f 6e 20 34 2e  MinGW version 4.
2740: 78 20 28 61 6e 64 20 68 69 67 68 65 72 29 2c 20  x (and higher), 
2750: 63 68 65 63 6b 20 74 6f 20 73 65 65 20 69 66 20  check to see if 
2760: 74 68 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54  the _USE_32BIT_T
2770: 49 4d 45 5f 54 0a 2a 2a 20 64 65 66 69 6e 65 20  IME_T.** define 
2780: 69 73 20 72 65 71 75 69 72 65 64 20 74 6f 20 6d  is required to m
2790: 61 69 6e 74 61 69 6e 20 62 69 6e 61 72 79 20 63  aintain binary c
27a0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
27b0: 68 20 74 68 65 20 4d 53 56 43 20 72 75 6e 74 69  h the MSVC runti
27c0: 6d 65 0a 2a 2a 20 6c 69 62 72 61 72 79 20 69 6e  me.** library in
27d0: 20 75 73 65 20 28 65 2e 67 2e 20 66 6f 72 20 57   use (e.g. for W
27e0: 69 6e 64 6f 77 73 20 58 50 29 2e 0a 2a 2f 0a 23  indows XP)..*/.#
27f0: 69 66 20 21 64 65 66 69 6e 65 64 28 5f 55 53 45  if !defined(_USE
2800: 5f 33 32 42 49 54 5f 54 49 4d 45 5f 54 29 20 26  _32BIT_TIME_T) &
2810: 26 20 21 64 65 66 69 6e 65 64 28 5f 55 53 45 5f  & !defined(_USE_
2820: 36 34 42 49 54 5f 54 49 4d 45 5f 54 29 20 26 26  64BIT_TIME_T) &&
2830: 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f   \.    defined(_
2840: 57 49 4e 33 32 29 20 26 26 20 21 64 65 66 69 6e  WIN32) && !defin
2850: 65 64 28 5f 57 49 4e 36 34 29 20 26 26 20 5c 0a  ed(_WIN64) && \.
2860: 20 20 20 20 64 65 66 69 6e 65 64 28 5f 5f 4d 49      defined(__MI
2870: 4e 47 57 5f 4d 41 4a 4f 52 5f 56 45 52 53 49 4f  NGW_MAJOR_VERSIO
2880: 4e 29 20 26 26 20 5f 5f 4d 49 4e 47 57 5f 4d 41  N) && __MINGW_MA
2890: 4a 4f 52 5f 56 45 52 53 49 4f 4e 20 3e 3d 20 34  JOR_VERSION >= 4
28a0: 20 26 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65   && \.    define
28b0: 64 28 5f 5f 4d 53 56 43 52 54 5f 5f 29 0a 23 20  d(__MSVCRT__).# 
28c0: 64 65 66 69 6e 65 20 5f 55 53 45 5f 33 32 42 49  define _USE_32BI
28d0: 54 5f 54 49 4d 45 5f 54 0a 23 65 6e 64 69 66 0a  T_TIME_T.#endif.
28e0: 0a 2f 2a 20 54 68 65 20 70 75 62 6c 69 63 20 53  ./* The public S
28f0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
2900: 20 20 54 68 65 20 5f 46 49 4c 45 5f 4f 46 46 53    The _FILE_OFFS
2910: 45 54 5f 42 49 54 53 20 6d 61 63 72 6f 20 6d 75  ET_BITS macro mu
2920: 73 74 20 61 70 70 65 61 72 0a 2a 2a 20 66 69 72  st appear.** fir
2930: 73 74 20 69 6e 20 51 4e 58 2e 20 20 41 6c 73 6f  st in QNX.  Also
2940: 2c 20 74 68 65 20 5f 55 53 45 5f 33 32 42 49 54  , the _USE_32BIT
2950: 5f 54 49 4d 45 5f 54 20 6d 61 63 72 6f 20 6d 75  _TIME_T macro mu
2960: 73 74 20 61 70 70 65 61 72 20 66 69 72 73 74 20  st appear first 
2970: 66 6f 72 0a 2a 2a 20 4d 69 6e 47 57 2e 0a 2a 2f  for.** MinGW..*/
2980: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
2990: 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74 65 33   Include sqlite3
29a0: 2e 68 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65  .h in the middle
29b0: 20 6f 66 20 73 71 6c 69 74 65 49 6e 74 2e 68 20   of sqliteInt.h 
29c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
29d0: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
29e0: 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69   Begin file sqli
29f0: 74 65 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  te3.h **********
2a00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2a10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
2a20: 0a 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74  ./*.** 2001 Sept
2a30: 65 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54  ember 15.**.** T
2a40: 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61  he author discla
2a50: 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f  ims copyright to
2a60: 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64   this source cod
2a70: 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a  e.  In place of.
2a80: 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63  ** a legal notic
2a90: 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65  e, here is a ble
2aa0: 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20  ssing:.**.**    
2ab0: 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20  May you do good 
2ac0: 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a  and not evil..**
2ad0: 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64      May you find
2ae0: 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72   forgiveness for
2af0: 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f   yourself and fo
2b00: 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a  rgive others..**
2b10: 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72      May you shar
2b20: 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20  e freely, never 
2b30: 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e  taking more than
2b40: 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a   you give..**.**
2b50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2b60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2b70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2b80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2b90: 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20  *******.** This 
2ba0: 68 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69  header file defi
2bb0: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
2bc0: 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74  e that the SQLit
2bd0: 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65  e library.** pre
2be0: 73 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20  sents to client 
2bf0: 70 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20  programs.  If a 
2c00: 43 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75  C-function, stru
2c10: 63 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c  cture, datatype,
2c20: 0a 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20  .** or constant 
2c30: 64 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20  definition does 
2c40: 6e 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68  not appear in th
2c50: 69 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74  is file, then it
2c60: 20 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62   is.** not a pub
2c70: 6c 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51  lished API of SQ
2c80: 4c 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74  Lite, is subject
2c90: 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f   to change witho
2ca0: 75 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e  ut.** notice, an
2cb0: 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
2cc0: 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72  referenced by pr
2cd0: 6f 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20  ograms that use 
2ce0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f  SQLite..**.** So
2cf0: 6d 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69  me of the defini
2d00: 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69  tions that are i
2d10: 6e 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20  n this file are 
2d20: 6d 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78  marked as.** "ex
2d30: 70 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78  perimental".  Ex
2d40: 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72  perimental inter
2d50: 66 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c  faces are normal
2d60: 6c 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72  ly new.** featur
2d70: 65 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65  es recently adde
2d80: 64 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65  d to SQLite.  We
2d90: 20 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61   do not anticipa
2da0: 74 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f  te changes.** to
2db0: 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e   experimental in
2dc0: 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73  terfaces but res
2dd0: 65 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74  erve the right t
2de0: 6f 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61  o make minor cha
2df0: 6e 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72  nges.** if exper
2e00: 69 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22  ience from use "
2e10: 69 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67  in the wild" sug
2e20: 67 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65  gest such change
2e30: 73 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a  s are prudent..*
2e40: 2a 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61  *.** The officia
2e50: 6c 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49  l C-language API
2e60: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
2e70: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72  or SQLite is der
2e80: 69 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d  ived.** from com
2e90: 6d 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69  ments in this fi
2ea0: 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69  le.  This file i
2eb0: 73 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74  s the authoritat
2ec0: 69 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e  ive source.** on
2ed0: 20 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65   how SQLite inte
2ee0: 72 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f  rfaces are suppo
2ef0: 73 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a  sed to operate..
2f00: 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  **.** The name o
2f10: 66 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65  f this file unde
2f20: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
2f30: 6d 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73  management is "s
2f40: 71 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20  qlite.h.in"..** 
2f50: 54 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b  The makefile mak
2f60: 65 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68  es some minor ch
2f70: 61 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69  anges to this fi
2f80: 6c 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65  le (such as inse
2f90: 72 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72  rting.** the ver
2fa0: 73 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64  sion number) and
2fb0: 20 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d   changes its nam
2fc0: 65 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22  e to "sqlite3.h"
2fd0: 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74   as.** part of t
2fe0: 68 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73  he build process
2ff0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
3000: 49 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53  ITE3_H.#define S
3010: 51 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64  QLITE3_H.#includ
3020: 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20  e <stdarg.h>    
3030: 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74   /* Needed for t
3040: 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66  he definition of
3050: 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a   va_list */../*.
3060: 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20  ** Make sure we 
3070: 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74  can call this st
3080: 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f  uff from C++..*/
3090: 0a 23 69 66 20 30 0a 65 78 74 65 72 6e 20 22 43  .#if 0.extern "C
30a0: 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a  " {.#endif.../*.
30b0: 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65 20 61  ** Provide the a
30c0: 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72 72 69  bility to overri
30d0: 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61 74 75  de linkage featu
30e0: 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74 65 72  res of the inter
30f0: 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  face..*/.#ifndef
3100: 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23   SQLITE_EXTERN.#
3110: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45   define SQLITE_E
3120: 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e  XTERN extern.#en
3130: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
3140: 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20  TE_API.# define 
3150: 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69  SQLITE_API.#endi
3160: 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  f.#ifndef SQLITE
3170: 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e 65 20  _CDECL.# define 
3180: 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23 65 6e  SQLITE_CDECL.#en
3190: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
31a0: 54 45 5f 41 50 49 43 41 4c 4c 0a 23 20 64 65 66  TE_APICALL.# def
31b0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 43 41  ine SQLITE_APICA
31c0: 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65  LL.#endif.#ifnde
31d0: 66 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  f SQLITE_STDCALL
31e0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
31f0: 5f 53 54 44 43 41 4c 4c 20 53 51 4c 49 54 45 5f  _STDCALL SQLITE_
3200: 41 50 49 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 23  APICALL.#endif.#
3210: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 41  ifndef SQLITE_CA
3220: 4c 4c 42 41 43 4b 0a 23 20 64 65 66 69 6e 65 20  LLBACK.# define 
3230: 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41 43 4b 0a  SQLITE_CALLBACK.
3240: 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53  #endif.#ifndef S
3250: 51 4c 49 54 45 5f 53 59 53 41 50 49 0a 23 20 64  QLITE_SYSAPI.# d
3260: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 53  efine SQLITE_SYS
3270: 41 50 49 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  API.#endif../*.*
3280: 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d 61  * These no-op ma
3290: 63 72 6f 73 20 61 72 65 20 75 73 65 64 20 69 6e  cros are used in
32a0: 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72 66   front of interf
32b0: 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68 6f  aces to mark tho
32c0: 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  se.** interfaces
32d0: 20 61 73 20 65 69 74 68 65 72 20 64 65 70 72 65   as either depre
32e0: 63 61 74 65 64 20 6f 72 20 65 78 70 65 72 69 6d  cated or experim
32f0: 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70 6c  ental.  New appl
3300: 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
3310: 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72 65  ld not use depre
3320: 63 61 74 65 64 20 69 6e 74 65 72 66 61 63 65 73  cated interfaces
3330: 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70 70   - they are supp
3340: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
3350: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
3360: 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70 6c  lity only.  Appl
3370: 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73 20  ication writers 
3380: 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65 20  should be aware 
3390: 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d 65  that.** experime
33a0: 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  ntal interfaces 
33b0: 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20 63  are subject to c
33c0: 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20 72  hange in point r
33d0: 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  eleases..**.** T
33e0: 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65 64  hese macros used
33f0: 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20 76   to resolve to v
3400: 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66 20  arious kinds of 
3410: 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20 74  compiler magic t
3420: 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65 6e  hat.** would gen
3430: 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d 65  erate warning me
3440: 73 73 61 67 65 73 20 77 68 65 6e 20 74 68 65 79  ssages when they
3450: 20 77 65 72 65 20 75 73 65 64 2e 20 20 42 75 74   were used.  But
3460: 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65   that.** compile
3470: 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75 70  r magic ended up
3480: 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63 68   generating such
3490: 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75 67   a flurry of bug
34a0: 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61 74   reports.** that
34b0: 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20 69   we have taken i
34c0: 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67 6f  t all out and go
34d0: 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e 67  ne back to using
34e0: 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20   simple.** noop 
34f0: 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69  macros..*/.#defi
3500: 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ne SQLITE_DEPREC
3510: 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51 4c  ATED.#define SQL
3520: 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
3530: 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20 74  ../*.** Ensure t
3540: 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65 72  hese symbols wer
3550: 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62 79  e not defined by
3560: 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20 68   some previous h
3570: 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23  eader file..*/.#
3580: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
3590: 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51 4c  SION.# undef SQL
35a0: 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e 64  ITE_VERSION.#end
35b0: 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  if.#ifdef SQLITE
35c0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a  _VERSION_NUMBER.
35d0: 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 56  # undef SQLITE_V
35e0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65  ERSION_NUMBER.#e
35f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
3600: 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
3610: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
3620: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a  on Numbers.**.**
3630: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56   ^(The [SQLITE_V
3640: 45 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72 6f  ERSION] C prepro
3650: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e 20  cessor macro in 
3660: 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68 65  the sqlite3.h he
3670: 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74 65  ader.** evaluate
3680: 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  s to a string li
3690: 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74 68  teral that is th
36a0: 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  e SQLite version
36b0: 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 61   in the.** forma
36c0: 74 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65 20  t "X.Y.Z" where 
36d0: 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20 76  X is the major v
36e0: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 61  ersion number (a
36f0: 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20 53  lways 3 for.** S
3700: 51 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69 73  QLite3) and Y is
3710: 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73 69   the minor versi
3720: 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a 20  on number and Z 
3730: 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20 6e  is the release n
3740: 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68  umber.)^.** ^(Th
3750: 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  e [SQLITE_VERSIO
3760: 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65 70  N_NUMBER] C prep
3770: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 72  rocessor macro r
3780: 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69 6e  esolves to an in
3790: 74 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74 68  teger.** with th
37a0: 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30 30  e value (X*10000
37b0: 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a 29  00 + Y*1000 + Z)
37c0: 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e 64   where X, Y, and
37d0: 20 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65 0a   Z are the same.
37e0: 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64 20  ** numbers used 
37f0: 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  in [SQLITE_VERSI
3800: 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53 51  ON].)^.** The SQ
3810: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
3820: 42 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76 65  BER for any give
3830: 6e 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  n release of SQL
3840: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a  ite will also.**
3850: 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
3860: 74 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f 6d  the release from
3870: 20 77 68 69 63 68 20 69 74 20 69 73 20 64 65 72   which it is der
3880: 69 76 65 64 2e 20 20 45 69 74 68 65 72 20 59 20  ived.  Either Y 
3890: 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64 20  will.** be held 
38a0: 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20 77  constant and Z w
38b0: 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74  ill be increment
38c0: 65 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69 6c  ed or else Y wil
38d0: 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64  l be incremented
38e0: 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62  .** and Z will b
38f0: 65 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f 2e  e reset to zero.
3900: 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 5b 76 65  .**.** Since [ve
3910: 72 73 69 6f 6e 20 33 2e 36 2e 31 38 5d 20 28 5b  rsion 3.6.18] ([
3920: 64 61 74 65 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c  dateof:3.6.18]),
3930: 20 0a 2a 2a 20 53 51 4c 69 74 65 20 73 6f 75 72   .** SQLite sour
3940: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
3950: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
3960: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
3970: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
3980: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
3990: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
39a0: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
39b0: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
39c0: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
39d0: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
39e0: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
39f0: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
3a00: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
3a10: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
3a20: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
3a30: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
3a40: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
3a50: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
3a60: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
3a70: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
3a80: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
3a90: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
3aa0: 64 20 61 20 53 48 41 31 0a 2a 2a 20 6f 72 20 53  d a SHA1.** or S
3ab0: 48 41 33 2d 32 35 36 20 68 61 73 68 20 6f 66 20  HA3-256 hash of 
3ac0: 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63  the entire sourc
3ad0: 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  e tree..**.** Se
3ae0: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
3af0: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a  _libversion()],.
3b00: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  ** [sqlite3_libv
3b10: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d  ersion_number()]
3b20: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  , [sqlite3_sourc
3b30: 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  eid()],.** [sqli
3b40: 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  te_version()] an
3b50: 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65  d [sqlite_source
3b60: 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  _id()]..*/.#defi
3b70: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
3b80: 4e 20 20 20 20 20 20 20 20 22 33 2e 31 39 2e 32  N        "3.19.2
3b90: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ".#define SQLITE
3ba0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
3bb0: 33 30 31 39 30 30 32 0a 23 64 65 66 69 6e 65 20  3019002.#define 
3bc0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
3bd0: 20 20 20 20 20 20 22 32 30 31 37 2d 30 35 2d 32        "2017-05-2
3be0: 35 20 31 36 3a 35 30 3a 32 37 20 65 64 62 34 65  5 16:50:27 edb4e
3bf0: 38 31 39 62 30 63 30 35 38 63 37 64 37 34 64 32  819b0c058c7d74d2
3c00: 37 65 62 64 31 34 63 63 35 63 65 62 32 62 61 64  7ebd14cc5ceb2bad
3c10: 36 61 36 31 34 34 61 34 38 36 61 39 37 30 31 38  6a6144a486a97018
3c20: 32 62 37 61 66 65 33 66 38 62 39 22 0a 0a 2f 2a  2b7afe3f8b9"../*
3c30: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
3c40: 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  n-Time Library V
3c50: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a  ersion Numbers.*
3c60: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
3c70: 74 65 33 5f 76 65 72 73 69 6f 6e 20 73 71 6c 69  te3_version sqli
3c80: 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a  te3_sourceid.**.
3c90: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61  ** These interfa
3ca0: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20  ces provide the 
3cb0: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
3cc0: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   as the [SQLITE_
3cd0: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51  VERSION],.** [SQ
3ce0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
3cf0: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  BER], and [SQLIT
3d00: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
3d10: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
3d20: 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73  os.** but are as
3d30: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
3d40: 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61  e library instea
3d50: 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20  d of the header 
3d60: 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75  file.  ^(Cautiou
3d70: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73  s.** programmers
3d80: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61   might include a
3d90: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
3da0: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ts in their appl
3db0: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65  ication to.** ve
3dc0: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73  rify that values
3dd0: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
3de0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  se interfaces ma
3df0: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69  tch the macros i
3e00: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c  n.** the header,
3e10: 20 61 6e 64 20 74 68 75 73 20 65 6e 73 75 72 65   and thus ensure
3e20: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63   that the applic
3e30: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70  ation is.** comp
3e40: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69  iled with matchi
3e50: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68  ng library and h
3e60: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a  eader files..**.
3e70: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
3e80: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20  pre>.** assert( 
3e90: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
3ea0: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c  on_number()==SQL
3eb0: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
3ec0: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  ER );.** assert(
3ed0: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
3ee0: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54  sourceid(),SQLIT
3ef0: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20  E_SOURCE_ID)==0 
3f00: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
3f10: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62  rcmp(sqlite3_lib
3f20: 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45  version(),SQLITE
3f30: 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a  _VERSION)==0 );.
3f40: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
3f50: 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
3f60: 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  The sqlite3_vers
3f70: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
3f80: 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74  stant contains t
3f90: 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49  he text of [SQLI
3fa0: 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d  TE_VERSION].** m
3fb0: 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69  acro.  ^The sqli
3fc0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
3fd0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
3fe0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
3ff0: 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c  he.** to the sql
4000: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
4010: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
4020: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
4030: 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e  version().** fun
4040: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65  ction is provide
4050: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c  d for use in DLL
4060: 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72  s since DLL user
4070: 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74  s usually do not
4080: 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20   have.** direct 
4090: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67  access to string
40a0: 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69   constants withi
40b0: 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65  n the DLL.  ^The
40c0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  .** sqlite3_libv
40d0: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20  ersion_number() 
40e0: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
40f0: 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61   an integer equa
4100: 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  l to.** [SQLITE_
4110: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
4120: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
4130: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
4140: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
4150: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
4160: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
4170: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
4180: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
4190: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
41a0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
41b0: 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  or macro..**.** 
41c0: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
41d0: 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64  e_version()] and
41e0: 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f   [sqlite_source_
41f0: 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  id()]..*/.SQLITE
4200: 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
4210: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
4220: 5d 20 3d 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ] = SQLITE_VERSI
4230: 4f 4e 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  ON;.SQLITE_API c
4240: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
4250: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f  e3_libversion(vo
4260: 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
4270: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
4280: 74 65 33 5f 73 6f 75 72 63 65 69 64 28 76 6f 69  te3_sourceid(voi
4290: 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
42a0: 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  nt sqlite3_libve
42b0: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69  rsion_number(voi
42c0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
42d0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
42e0: 62 72 61 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f  brary Compilatio
42f0: 6e 20 4f 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f  n Options Diagno
4300: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stics.**.** ^The
4310: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
4320: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 20 66 75  option_used() fu
4330: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 30  nction returns 0
4340: 20 6f 72 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61   or 1 .** indica
4350: 74 69 6e 67 20 77 68 65 74 68 65 72 20 74 68 65  ting whether the
4360: 20 73 70 65 63 69 66 69 65 64 20 6f 70 74 69 6f   specified optio
4370: 6e 20 77 61 73 20 64 65 66 69 6e 65 64 20 61 74  n was defined at
4380: 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d   .** compile tim
4390: 65 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  e.  ^The SQLITE_
43a0: 20 70 72 65 66 69 78 20 6d 61 79 20 62 65 20 6f   prefix may be o
43b0: 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
43c0: 0a 2a 2a 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20  .** option name 
43d0: 70 61 73 73 65 64 20 74 6f 20 73 71 6c 69 74 65  passed to sqlite
43e0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
43f0: 75 73 65 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20  used().  .**.** 
4400: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ^The sqlite3_com
4410: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
4420: 20 66 75 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73   function allows
4430: 20 69 74 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76   iterating.** ov
4440: 65 72 20 74 68 65 20 6c 69 73 74 20 6f 66 20 6f  er the list of o
4450: 70 74 69 6f 6e 73 20 74 68 61 74 20 77 65 72 65  ptions that were
4460: 20 64 65 66 69 6e 65 64 20 61 74 20 63 6f 6d 70   defined at comp
4470: 69 6c 65 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72  ile time by.** r
4480: 65 74 75 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74  eturning the N-t
4490: 68 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f  h compile time o
44a0: 70 74 69 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e  ption string.  ^
44b0: 49 66 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  If N is out of r
44c0: 61 6e 67 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  ange,.** sqlite3
44d0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
44e0: 65 74 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e  et() returns a N
44f0: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
4500: 68 65 20 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70  he SQLITE_ .** p
4510: 72 65 66 69 78 20 69 73 20 6f 6d 69 74 74 65 64  refix is omitted
4520: 20 66 72 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67   from any string
4530: 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 0a 2a  s returned by .*
4540: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  * sqlite3_compil
4550: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a  eoption_get()..*
4560: 2a 0a 2a 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f  *.** ^Support fo
4570: 72 20 74 68 65 20 64 69 61 67 6e 6f 73 74 69 63  r the diagnostic
4580: 20 66 75 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74   functions sqlit
4590: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
45a0: 5f 75 73 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73  _used().** and s
45b0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
45c0: 74 69 6f 6e 5f 67 65 74 28 29 20 6d 61 79 20 62  tion_get() may b
45d0: 65 20 6f 6d 69 74 74 65 64 20 62 79 20 73 70 65  e omitted by spe
45e0: 63 69 66 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20  cifying the .** 
45f0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d  [SQLITE_OMIT_COM
4600: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
4610: 5d 20 6f 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70  ] option at comp
4620: 69 6c 65 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ile time..**.** 
4630: 53 65 65 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75  See also: SQL fu
4640: 6e 63 74 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f  nctions [sqlite_
4650: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
4660: 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
4670: 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  lite_compileopti
4680: 6f 6e 5f 67 65 74 28 29 5d 20 61 6e 64 20 74 68  on_get()] and th
4690: 65 20 5b 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f  e [compile_optio
46a0: 6e 73 20 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23  ns pragma]..*/.#
46b0: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
46c0: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e  IT_COMPILEOPTION
46d0: 5f 44 49 41 47 53 0a 53 51 4c 49 54 45 5f 41 50  _DIAGS.SQLITE_AP
46e0: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
46f0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
4700: 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70  (const char *zOp
4710: 74 4e 61 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41  tName);.SQLITE_A
4720: 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
4730: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
4740: 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b  tion_get(int N);
4750: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
4760: 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 54 6f  API3REF: Test To
4770: 20 53 65 65 20 49 66 20 54 68 65 20 4c 69 62 72   See If The Libr
4780: 61 72 79 20 49 73 20 54 68 72 65 61 64 73 61 66  ary Is Threadsaf
4790: 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
47a0: 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28  ite3_threadsafe(
47b0: 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  ) function retur
47c0: 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f  ns zero if and o
47d0: 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65  nly if.** SQLite
47e0: 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69   was compiled wi
47f0: 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f 64 65  th mutexing code
4800: 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74 6f 20   omitted due to 
4810: 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  the.** [SQLITE_T
4820: 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d 70 69  HREADSAFE] compi
4830: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62  le-time option b
4840: 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a  eing set to 0..*
4850: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61 6e 20  *.** SQLite can 
4860: 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  be compiled with
4870: 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75 74 65   or without mute
4880: 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68  xes.  When.** th
4890: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
48a0: 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f 63 65  SAFE] C preproce
48b0: 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20 31 20  ssor macro is 1 
48c0: 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a  or 2, mutexes.**
48d0: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64   are enabled and
48e0: 20 53 51 4c 69 74 65 20 69 73 20 74 68 72 65 61   SQLite is threa
48f0: 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74 68 65  dsafe.  When the
4900: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
4910: 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20 69 73  ADSAFE] macro is
4920: 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65   0, .** the mute
4930: 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65 64 2e  xes are omitted.
4940: 20 20 57 69 74 68 6f 75 74 20 74 68 65 20 6d 75    Without the mu
4950: 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e 6f 74  texes, it is not
4960: 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20   safe.** to use 
4970: 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72 65 6e  SQLite concurren
4980: 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68  tly from more th
4990: 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a  an one thread..*
49a0: 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75  *.** Enabling mu
49b0: 74 65 78 65 73 20 69 6e 63 75 72 73 20 61 20 6d  texes incurs a m
49c0: 65 61 73 75 72 61 62 6c 65 20 70 65 72 66 6f 72  easurable perfor
49d0: 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a  mance penalty..*
49e0: 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20 69 73  * So if speed is
49f0: 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72   of utmost impor
4a00: 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65 73 20  tance, it makes 
4a10: 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62 6c 65  sense to disable
4a20: 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 2e  .** the mutexes.
4a30: 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69 6d 75    But for maximu
4a40: 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65 78 65  m safety, mutexe
4a50: 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e 61 62  s should be enab
4a60: 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66  led..** ^The def
4a70: 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 73  ault behavior is
4a80: 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74 6f 20   for mutexes to 
4a90: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  be enabled..**.*
4aa0: 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
4ab0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 62 79 20   can be used by 
4ac0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
4ad0: 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
4ae0: 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20   the.** version 
4af0: 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74 20 69  of SQLite that i
4b00: 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61  t is linking aga
4b10: 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69 6c 65  inst was compile
4b20: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 64 65  d with.** the de
4b30: 73 69 72 65 64 20 73 65 74 74 69 6e 67 20 6f 66  sired setting of
4b40: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
4b50: 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a  EADSAFE] macro..
4b60: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
4b70: 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74  face only report
4b80: 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65  s on the compile
4b90: 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65 74 74  -time mutex sett
4ba0: 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53  ing.** of the [S
4bb0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
4bc0: 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51 4c 69  ] flag.  If SQLi
4bd0: 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
4be0: 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48  ith.** SQLITE_TH
4bf0: 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20 3d 32  READSAFE=1 or =2
4c00: 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20 61 72   then mutexes ar
4c10: 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
4c20: 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20  ault but.** can 
4c30: 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61 72 74  be fully or part
4c40: 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 20 75  ially disabled u
4c50: 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b  sing a call to [
4c60: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
4c70: 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 65  ].** with the ve
4c80: 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  rbs [SQLITE_CONF
4c90: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
4ca0: 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  , [SQLITE_CONFIG
4cb0: 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a  _MULTITHREAD],.*
4cc0: 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  * or [SQLITE_CON
4cd0: 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 2e  FIG_SERIALIZED].
4ce0: 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76    ^(The return v
4cf0: 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73  alue of the.** s
4d00: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
4d10: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  e() function sho
4d20: 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70  ws only the comp
4d30: 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67  ile-time setting
4d40: 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61   of.** thread sa
4d50: 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75  fety, not any ru
4d60: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74  n-time changes t
4d70: 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d  o that setting m
4d80: 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65  ade by.** sqlite
4d90: 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f  3_config(). In o
4da0: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
4db0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
4dc0: 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  m sqlite3_thread
4dd0: 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63  safe().** is unc
4de0: 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20  hanged by calls 
4df0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
4e00: 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  g().)^.**.** See
4e10: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
4e20: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74  mode] documentat
4e30: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
4e40: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
4e50: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
4e60: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  t sqlite3_thread
4e70: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  safe(void);../*.
4e80: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
4e90: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
4ea0: 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f   Handle.** KEYWO
4eb0: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63  RDS: {database c
4ec0: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61  onnection} {data
4ed0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
4ee0: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65  }.**.** Each ope
4ef0: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
4f00: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  e is represented
4f10: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   by a pointer to
4f20: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a   an instance of.
4f30: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74  ** the opaque st
4f40: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73  ructure named "s
4f50: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20  qlite3".  It is 
4f60: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20  useful to think 
4f70: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a  of an sqlite3.**
4f80: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f   pointer as an o
4f90: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c  bject.  The [sql
4fa0: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
4fb0: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
4fc0: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
4fd0: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
4fe0: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20  erfaces are its 
4ff0: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e  constructors, an
5000: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
5010: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
5020: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 5d 20  te3_close_v2()] 
5030: 61 72 65 20 69 74 73 20 64 65 73 74 72 75 63 74  are its destruct
5040: 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72 65 20  ors.  There are 
5050: 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 69 6e  many other.** in
5060: 74 65 72 66 61 63 65 73 20 28 73 75 63 68 20 61  terfaces (such a
5070: 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  s.** [sqlite3_pr
5080: 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71  epare_v2()], [sq
5090: 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
50a0: 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a 2a 2a  ction()], and.**
50b0: 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
50c0: 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e 61 6d  imeout()] to nam
50d0: 65 20 62 75 74 20 74 68 72 65 65 29 20 74 68 61  e but three) tha
50e0: 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20 6f 6e  t are methods on
50f0: 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 20 6f   an.** sqlite3 o
5100: 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65 64 65  bject..*/.typede
5110: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
5120: 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a 2a 2a   sqlite3;../*.**
5130: 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d 42 69   CAPI3REF: 64-Bi
5140: 74 20 49 6e 74 65 67 65 72 20 54 79 70 65 73 0a  t Integer Types.
5150: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
5160: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
5170: 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20 42 65  _uint64.**.** Be
5180: 63 61 75 73 65 20 74 68 65 72 65 20 69 73 20 6e  cause there is n
5190: 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f 72 6d  o cross-platform
51a0: 20 77 61 79 20 74 6f 20 73 70 65 63 69 66 79 20   way to specify 
51b0: 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 74  64-bit integer t
51c0: 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ypes.** SQLite i
51d0: 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65 66 73  ncludes typedefs
51e0: 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69 67 6e   for 64-bit sign
51f0: 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65 64 20  ed and unsigned 
5200: 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  integers..**.** 
5210: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  The sqlite3_int6
5220: 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 75 69  4 and sqlite3_ui
5230: 6e 74 36 34 20 61 72 65 20 74 68 65 20 70 72 65  nt64 are the pre
5240: 66 65 72 72 65 64 20 74 79 70 65 20 64 65 66 69  ferred type defi
5250: 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68 65 20  nitions..** The 
5260: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61 6e 64  sqlite_int64 and
5270: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
5280: 79 70 65 73 20 61 72 65 20 73 75 70 70 6f 72 74  ypes are support
5290: 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
52a0: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
52b0: 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  y only..**.** ^T
52c0: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  he sqlite3_int64
52d0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e 74 36   and sqlite_int6
52e0: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
52f0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
5300: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39 32 32  .** between -922
5310: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 38  3372036854775808
5320: 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30 33 36   and +9223372036
5330: 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c 75 73  854775807 inclus
5340: 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ive.  ^The.** sq
5350: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 6e 64  lite3_uint64 and
5360: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 74   sqlite_uint64 t
5370: 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65 20 69  ypes can store i
5380: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 0a 2a  nteger values .*
5390: 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  * between 0 and 
53a0: 2b 31 38 34 34 36 37 34 34 30 37 33 37 30 39 35  +184467440737095
53b0: 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76 65 2e  51615 inclusive.
53c0: 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54  .*/.#ifdef SQLIT
53d0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20 20 74  E_INT64_TYPE.  t
53e0: 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f 49 4e  ypedef SQLITE_IN
53f0: 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f  T64_TYPE sqlite_
5400: 69 6e 74 36 34 3b 0a 23 20 69 66 64 65 66 20 53  int64;.# ifdef S
5410: 51 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59 50  QLITE_UINT64_TYP
5420: 45 0a 20 20 20 20 74 79 70 65 64 65 66 20 53 51  E.    typedef SQ
5430: 4c 49 54 45 5f 55 49 4e 54 36 34 5f 54 59 50 45  LITE_UINT64_TYPE
5440: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
5450: 23 20 65 6c 73 65 20 20 0a 20 20 20 20 74 79 70  # else  .    typ
5460: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
5470: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
5480: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
5490: 20 65 6e 64 69 66 0a 23 65 6c 69 66 20 64 65 66   endif.#elif def
54a0: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c  ined(_MSC_VER) |
54b0: 7c 20 64 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c  | defined(__BORL
54c0: 41 4e 44 43 5f 5f 29 0a 20 20 74 79 70 65 64 65  ANDC__).  typede
54d0: 66 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  f __int64 sqlite
54e0: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
54f0: 66 20 75 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74  f unsigned __int
5500: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
5510: 3b 0a 23 65 6c 73 65 0a 20 20 74 79 70 65 64 65  ;.#else.  typede
5520: 66 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20  f long long int 
5530: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
5540: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
5550: 20 6c 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73   long long int s
5560: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
5570: 6e 64 69 66 0a 74 79 70 65 64 65 66 20 73 71 6c  ndif.typedef sql
5580: 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  ite_int64 sqlite
5590: 33 5f 69 6e 74 36 34 3b 0a 74 79 70 65 64 65 66  3_int64;.typedef
55a0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 20 73   sqlite_uint64 s
55b0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a  qlite3_uint64;..
55c0: 2f 2a 0a 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69  /*.** If compili
55d0: 6e 67 20 66 6f 72 20 61 20 70 72 6f 63 65 73 73  ng for a process
55e0: 6f 72 20 74 68 61 74 20 6c 61 63 6b 73 20 66 6c  or that lacks fl
55f0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 73 75 70  oating point sup
5600: 70 6f 72 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74  port,.** substit
5610: 75 74 65 20 69 6e 74 65 67 65 72 20 66 6f 72 20  ute integer for 
5620: 66 6c 6f 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a  floating-point..
5630: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
5640: 5f 4f 4d 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50  _OMIT_FLOATING_P
5650: 4f 49 4e 54 0a 23 20 64 65 66 69 6e 65 20 64 6f  OINT.# define do
5660: 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  uble sqlite3_int
5670: 36 34 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  64.#endif../*.**
5680: 20 43 41 50 49 33 52 45 46 3a 20 43 6c 6f 73 69   CAPI3REF: Closi
5690: 6e 67 20 41 20 44 61 74 61 62 61 73 65 20 43 6f  ng A Database Co
56a0: 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 44 45 53 54  nnection.** DEST
56b0: 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65 33 0a  RUCTOR: sqlite3.
56c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
56d0: 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73  e3_close() and s
56e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
56f0: 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64  ) routines are d
5700: 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f  estructors.** fo
5710: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  r the [sqlite3] 
5720: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c  object..** ^Call
5730: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f  s to sqlite3_clo
5740: 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  se() and sqlite3
5750: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75  _close_v2() retu
5760: 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  rn [SQLITE_OK] i
5770: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  f.** the [sqlite
5780: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63  3] object is suc
5790: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f  cessfully destro
57a0: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f  yed and all asso
57b0: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72  ciated.** resour
57c0: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
57d0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ted..**.** ^If t
57e0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
57f0: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69  ection is associ
5800: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61  ated with unfina
5810: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a  lized prepared.*
5820: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20  * statements or 
5830: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
5840: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74  e3_backup object
5850: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  s then sqlite3_c
5860: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c  lose().** will l
5870: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73  eave the databas
5880: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
5890: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  n and return [SQ
58a0: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e  LITE_BUSY]..** ^
58b0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  If sqlite3_close
58c0: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
58d0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
58e0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
58f0: 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f 6f 72 20 75  ents.** and/or u
5900: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
5910: 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20  3_backups, then 
5920: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
5930: 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a  nection becomes.
5940: 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22  ** an unusable "
5950: 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69  zombie" which wi
5960: 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
5970: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
5980: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74  when the.** last
5990: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
59a0: 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
59b0: 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c   or the last sql
59c0: 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a  ite3_backup is.*
59d0: 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65  * finished.  The
59e0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
59f0: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
5a00: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5a10: 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c  e with.** host l
5a20: 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72  anguages that ar
5a30: 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63  e garbage collec
5a40: 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74  ted, and where t
5a50: 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63  he order in whic
5a60: 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73  h.** destructors
5a70: 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61   are called is a
5a80: 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  rbitrary..**.** 
5a90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
5aa0: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  uld [sqlite3_fin
5ab0: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
5ac0: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20  ] all [prepared 
5ad0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20  statements],.** 
5ae0: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
5af0: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c  ose | close] all
5b00: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
5b10: 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
5b20: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20  3_backup_finish 
5b30: 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73  | finish] all [s
5b40: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
5b50: 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65  bjects associate
5b60: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73  d.** with the [s
5b70: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
5b80: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69  rior to attempti
5b90: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
5ba0: 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20  object.  ^If.** 
5bb0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
5bc0: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20  () is called on 
5bd0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
5be0: 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69  ection] that sti
5bf0: 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61  ll has.** outsta
5c00: 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20  nding [prepared 
5c10: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c  statements], [BL
5c20: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
5c30: 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  /or.** [sqlite3_
5c40: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
5c50: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20  then it returns 
5c60: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 61 6e 64 20  [SQLITE_OK] and 
5c70: 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e  the deallocation
5c80: 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65 73  .** of resources
5c90: 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e 74   is deferred unt
5ca0: 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64  il all [prepared
5cb0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42   statements], [B
5cc0: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a  LOB handles],.**
5cd0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 61   and [sqlite3_ba
5ce0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 72  ckup] objects ar
5cf0: 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65 64  e also destroyed
5d00: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b  ..**.** ^If an [
5d10: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
5d20: 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68 69  is destroyed whi
5d30: 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  le a transaction
5d40: 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65   is open,.** the
5d50: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
5d60: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
5d70: 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
5d80: 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65 72   The C parameter
5d90: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f   to [sqlite3_clo
5da0: 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69  se(C)] and [sqli
5db0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d  te3_close_v2(C)]
5dc0: 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68  .** must be eith
5dd0: 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  er a NULL.** poi
5de0: 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69  nter or an [sqli
5df0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e  te3] object poin
5e00: 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ter obtained.** 
5e10: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70  from [sqlite3_op
5e20: 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
5e30: 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a  open16()], or.**
5e40: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
5e50: 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72  2()], and not pr
5e60: 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e  eviously closed.
5e70: 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
5e80: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20  ite3_close() or 
5e90: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
5ea0: 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  () with a NULL p
5eb0: 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65  ointer.** argume
5ec0: 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  nt is a harmless
5ed0: 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51 4c 49 54   no-op..*/.SQLIT
5ee0: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
5ef0: 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 2a  3_close(sqlite3*
5f00: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
5f10: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  t sqlite3_close_
5f20: 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  v2(sqlite3*);../
5f30: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
5f40: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
5f50: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
5f60: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
5f70: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
5f80: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
5f90: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
5fa0: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
5fb0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
5fc0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
5fd0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
5fe0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
5ff0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
6000: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
6010: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
6020: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
6030: 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
6040: 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite3.**.** The s
6050: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e  qlite3_exec() in
6060: 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f 6e  terface is a con
6070: 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65 72  venience wrapper
6080: 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
6090: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
60a0: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
60b0: 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
60c0: 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a  3_finalize()],.*
60d0: 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e  * that allows an
60e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
60f0: 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74 61  run multiple sta
6100: 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a  tements of SQL.*
6110: 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e 67  * without having
6120: 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f 66   to use a lot of
6130: 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20   C code. .**.** 
6140: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65  ^The sqlite3_exe
6150: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 75  c() interface ru
6160: 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  ns zero or more 
6170: 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a  UTF-8 encoded,.*
6180: 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
6190: 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65  rate SQL stateme
61a0: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 20  nts passed into 
61b0: 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
61c0: 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74  ,.** in the cont
61d0: 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61  ext of the [data
61e0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
61f0: 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69 74   passed in as it
6200: 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  s 1st.** argumen
6210: 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  t.  ^If the call
6220: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66  back function of
6230: 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e   the 3rd argumen
6240: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
6250: 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55  exec() is not NU
6260: 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69  LL, then it is i
6270: 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68 20  nvoked for each 
6280: 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f  result row.** co
6290: 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65 20  ming out of the 
62a0: 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73 74  evaluated SQL st
62b0: 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20  atements.  ^The 
62c0: 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  4th argument to.
62d0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
62e0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
62f0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
6300: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
6310: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
6320: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
6330: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
6340: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
6350: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
6360: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
6370: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
6380: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
6390: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
63a0: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
63b0: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
63c0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
63d0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
63e0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
63f0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
6400: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
6410: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
6420: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
6430: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
6440: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
6450: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
6460: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
6470: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
6480: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
6490: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
64a0: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
64b0: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
64c0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
64d0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
64e0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
64f0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
6500: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
6510: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
6520: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
6530: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
6540: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
6550: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
6560: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
6570: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
6580: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
6590: 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65  ter of.** sqlite
65a0: 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20 74  3_exec() after t
65b0: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
65c0: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f   string is no lo
65d0: 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20  nger needed..** 
65e0: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
65f0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
6600: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
6610: 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72  ULL and no error
6620: 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e  s.** occur, then
6630: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
6640: 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72  sets the pointer
6650: 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72 61   in its 5th para
6660: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c  meter to.** NULL
6670: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
6680: 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  g..**.** ^If an 
6690: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
66a0: 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
66b0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71  non-zero, the sq
66c0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
66d0: 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
66e0: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74  SQLITE_ABORT wit
66f0: 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68  hout invoking th
6700: 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e  e callback again
6710: 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20   and.** without 
6720: 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73  running any subs
6730: 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65  equent SQL state
6740: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
6750: 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  e 2nd argument t
6760: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
6770: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75  ec() callback fu
6780: 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a  nction is the.**
6790: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
67a0: 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
67b0: 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67 75  .  ^The 3rd argu
67c0: 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69  ment to the sqli
67d0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61  te3_exec().** ca
67e0: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
67f0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
6800: 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e  o strings obtain
6810: 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a  ed as if from.**
6820: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
6830: 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f  _text()], one fo
6840: 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20  r each column.  
6850: 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f  ^If an element o
6860: 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  f a.** result ro
6870: 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  w is NULL then t
6880: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
6890: 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20   string pointer 
68a0: 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  for the.** sqlit
68b0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
68c0: 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ck is a NULL poi
68d0: 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20  nter.  ^The 4th 
68e0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
68f0: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
6900: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  ) callback is an
6910: 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
6920: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68  rs to strings wh
6930: 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72  ere each.** entr
6940: 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68 65  y represents the
6950: 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70   name of corresp
6960: 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f  onding result co
6970: 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64  lumn as obtained
6980: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
6990: 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d  3_column_name()]
69a0: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
69b0: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
69c0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
69d0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
69e0: 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  r, a pointer.** 
69f0: 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
6a00: 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72  ng, or a pointer
6a10: 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f   that contains o
6a20: 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20 61  nly whitespace a
6a30: 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f  nd/or .** SQL co
6a40: 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20  mments, then no 
6a50: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
6a60: 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64  re evaluated and
6a70: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
6a80: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e   is not changed.
6a90: 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69  .**.** Restricti
6aa0: 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ons:.**.** <ul>.
6ab0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
6ac0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e 73  ication must ens
6ad0: 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73 74  ure that the 1st
6ae0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
6af0: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
6b00: 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64 20       is a valid 
6b10: 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  and open [databa
6b20: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
6b30: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
6b40: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
6b50: 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61   close the [data
6b60: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
6b70: 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a   specified by.**
6b80: 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61        the 1st pa
6b90: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
6ba0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
6bb0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
6bc0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c  s running..** <l
6bd0: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
6be0: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69  on must not modi
6bf0: 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  fy the SQL state
6c00: 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64  ment text passed
6c10: 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68   into.**      th
6c20: 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
6c30: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
6c40: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
6c50: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
6c60: 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53  g..** </ul>.*/.S
6c70: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
6c80: 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71  lite3_exec(.  sq
6c90: 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20  lite3*,         
6ca0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6cb0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
6cc0: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
6cd0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71    const char *sq
6ce0: 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
6cf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
6d00: 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
6d10: 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63  ted */.  int (*c
6d20: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
6d30: 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a  nt,char**,char**
6d40: 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  ),  /* Callback 
6d50: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
6d60: 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20  id *,           
6d70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6d80: 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20           /* 1st 
6d90: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
6da0: 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a  back */.  char *
6db0: 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20  *errmsg         
6dc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6dd0: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
6de0: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
6df0: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
6e00: 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64  3REF: Result Cod
6e10: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
6e20: 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66  {result code def
6e30: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
6e40: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63  Many SQLite func
6e50: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20  tions return an 
6e60: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63  integer result c
6e70: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74  ode from the set
6e80: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69   shown.** here i
6e90: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63  n order to indic
6ea0: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66  ate success or f
6eb0: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
6ec0: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
6ed0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
6ee0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
6ef0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
6f00: 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64  ee also: [extend
6f10: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64  ed result code d
6f20: 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23  efinitions].*/.#
6f30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
6f40: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
6f50: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
6f60: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
6f70: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
6f80: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
6f90: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
6fa0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
6fb0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
6fc0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
6fd0: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
6fe0: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
6ff0: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
7000: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
7010: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
7020: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
7030: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
7040: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
7050: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
7060: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
7070: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
7080: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
7090: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
70a0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
70b0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
70c0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
70d0: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
70e0: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
70f0: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
7100: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
7110: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
7120: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7130: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
7140: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
7150: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
7160: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
7170: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
7180: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
7190: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
71a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
71b0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
71c0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
71d0: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
71e0: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
71f0: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
7200: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
7210: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
7220: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
7230: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
7240: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7250: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
7260: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
7270: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
7280: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
7290: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
72a0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55  UND    12   /* U
72b0: 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e  nknown opcode in
72c0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
72d0: 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69  ntrol() */.#defi
72e0: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20  ne SQLITE_FULL  
72f0: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e        13   /* In
7300: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62  sertion failed b
7310: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20  ecause database 
7320: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69  is full */.#defi
7330: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
7340: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e  EN    14   /* Un
7350: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  able to open the
7360: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
7370: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7380: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20  _PROTOCOL    15 
7390: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f    /* Database lo
73a0: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f  ck protocol erro
73b0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
73c0: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20  ITE_EMPTY       
73d0: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  16   /* Database
73e0: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65   is empty */.#de
73f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45  fine SQLITE_SCHE
7400: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20  MA      17   /* 
7410: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  The database sch
7420: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23  ema changed */.#
7430: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f  define SQLITE_TO
7440: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f  OBIG      18   /
7450: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  * String or BLOB
7460: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69   exceeds size li
7470: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mit */.#define S
7480: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7490: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20    19   /* Abort 
74a0: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e  due to constrain
74b0: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23  t violation */.#
74c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
74d0: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f  SMATCH    20   /
74e0: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d  * Data type mism
74f0: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20  atch */.#define 
7500: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20  SQLITE_MISUSE   
7510: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61     21   /* Libra
7520: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63  ry used incorrec
7530: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tly */.#define S
7540: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20  QLITE_NOLFS     
7550: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f    22   /* Uses O
7560: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73  S features not s
7570: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74  upported on host
7580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
7590: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32  TE_AUTH        2
75a0: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61  3   /* Authoriza
75b0: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  tion denied */.#
75c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f  define SQLITE_FO
75d0: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f  RMAT      24   /
75e0: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61  * Auxiliary data
75f0: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f  base format erro
7600: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
7610: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20  ITE_RANGE       
7620: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61  25   /* 2nd para
7630: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
7640: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e  _bind out of ran
7650: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge */.#define SQ
7660: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20  LITE_NOTADB     
7670: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70   26   /* File op
7680: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74  ened that is not
7690: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
76a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
76b0: 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 32  TE_NOTICE      2
76c0: 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74  7   /* Notificat
76d0: 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 65  ions from sqlite
76e0: 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69  3_log() */.#defi
76f0: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
7700: 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57 61  G     28   /* Wa
7710: 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69  rnings from sqli
7720: 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65  te3_log() */.#de
7730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
7740: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
7750: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
7760: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
7770: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
7780: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
7790: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
77a0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
77b0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
77c0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
77d0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
77e0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
77f0: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
7800: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
7810: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
7820: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
7830: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  ns}.**.** In its
7840: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
7850: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
7860: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
7870: 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74  rn one of 30 int
7880: 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20  eger.** [result 
7890: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
78a0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
78b0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
78c0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
78d0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
78e0: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
78f0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
7900: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
7910: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
7920: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
7930: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
7940: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
7950: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
7960: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
7970: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
7980: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
7990: 38 20 5b 64 61 74 65 6f 66 3a 33 2e 33 2e 38 5d  8 [dateof:3.3.8]
79a0: 0a 2a 2a 20 61 6e 64 20 6c 61 74 65 72 29 20 69  .** and later) i
79b0: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72  nclude.** suppor
79c0: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  t for additional
79d0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68   result codes th
79e0: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20  at provide more 
79f0: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61  detailed informa
7a00: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72  tion.** about er
7a10: 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78 74  rors. These [ext
7a20: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
7a30: 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 20  es] are enabled 
7a40: 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f  or disabled.** o
7a50: 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73 65  n a per database
7a60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
7a70: 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  s using the.** [
7a80: 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
7a90: 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d  _result_codes()]
7aa0: 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 65   API.  Or, the e
7ab0: 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f 72  xtended code for
7ac0: 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63  .** the most rec
7ad0: 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62 65  ent error can be
7ae0: 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67 0a   obtained using.
7af0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65  ** [sqlite3_exte
7b00: 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e  nded_errcode()].
7b10: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
7b20: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
7b30: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
7b40: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
7b50: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7b60: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
7b70: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
7b80: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
7b90: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7ba0: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
7bb0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7bc0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
7bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7be0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
7bf0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
7c00: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
7c10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7c20: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
7c30: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7c40: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
7c50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
7c60: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
7c70: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
7c80: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
7c90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
7ca0: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
7cb0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
7cc0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
7cd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
7ce0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
7cf0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
7d00: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
7d10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
7d20: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
7d30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
7d40: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
7d50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
7d60: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
7d70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
7d80: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
7d90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
7da0: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
7db0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
7dc0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
7dd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
7de0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
7df0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
7e00: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
7e10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
7e20: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
7e30: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
7e40: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
7e50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
7e60: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
7e70: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
7e80: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
7e90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
7ea0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
7eb0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
7ec0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
7ed0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
7ee0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
7ef0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
7f00: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
7f10: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
7f20: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
7f30: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
7f40: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
7f50: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
7f60: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
7f70: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
7f80: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
7f90: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
7fa0: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
7fb0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
7fc0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
7fd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
7fe0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
7ff0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
8000: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
8010: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
8020: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
8030: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
8040: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
8050: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
8060: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
8070: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
8080: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
8090: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
80a0: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
80b0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
80c0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
80d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
80e0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
80f0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
8100: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
8110: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
8120: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
8130: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
8140: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
8150: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
8160: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
8170: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
8180: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
8190: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
81a0: 56 4e 4f 44 45 20 20 20 20 20 20 20 20 20 20 20  VNODE           
81b0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
81c0: 7c 20 28 32 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (27<<8)).#defi
81d0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
81e0: 41 55 54 48 20 20 20 20 20 20 20 20 20 20 20 20  AUTH            
81f0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
8200: 7c 20 28 32 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (28<<8)).#defi
8210: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
8220: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
8230: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
8240: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
8250: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
8260: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
8270: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
8280: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
8290: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
82a0: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20  _SNAPSHOT       
82b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
82c0: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64     |  (2<<8)).#d
82d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
82e0: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
82f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
8300: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
8310: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
8320: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
8330: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
8340: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
8350: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
8360: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
8370: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
8380: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
8390: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
83a0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56  TE_CANTOPEN_CONV
83b0: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
83c0: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34  TE_CANTOPEN | (4
83d0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
83e0: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
83f0: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
8400: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
8410: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
8420: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
8430: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
8440: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
8450: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
8460: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
8470: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
8480: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
8490: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
84a0: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
84b0: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  LY_ROLLBACK     
84c0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
84d0: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  LY | (3<<8)).#de
84e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
84f0: 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20  ONLY_DBMOVED    
8500: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
8510: 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23  ONLY | (4<<8)).#
8520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
8530: 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  ORT_ROLLBACK    
8540: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42        (SQLITE_AB
8550: 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ORT | (2<<8)).#d
8560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
8570: 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20  STRAINT_CHECK   
8580: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
8590: 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29  STRAINT | (1<<8)
85a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
85b0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d  _CONSTRAINT_COMM
85c0: 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45  ITHOOK   (SQLITE
85d0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32  _CONSTRAINT | (2
85e0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
85f0: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
8600: 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51  FOREIGNKEY   (SQ
8610: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
8620: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
8630: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
8640: 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  INT_FUNCTION    
8650: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
8660: 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  INT | (4<<8)).#d
8670: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
8680: 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20  STRAINT_NOTNULL 
8690: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
86a0: 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29  STRAINT | (5<<8)
86b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
86c0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d  _CONSTRAINT_PRIM
86d0: 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45  ARYKEY   (SQLITE
86e0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36  _CONSTRAINT | (6
86f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
8700: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
8710: 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51  TRIGGER      (SQ
8720: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
8730: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
8740: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
8750: 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20  INT_UNIQUE      
8760: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
8770: 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  INT | (8<<8)).#d
8780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
8790: 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20  STRAINT_VTAB    
87a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
87b0: 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29  STRAINT | (9<<8)
87c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
87d0: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49  _CONSTRAINT_ROWI
87e0: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
87f0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30  _CONSTRAINT |(10
8800: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
8810: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
8820: 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51  VER_WAL      (SQ
8830: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31  LITE_NOTICE | (1
8840: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
8850: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
8860: 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51  VER_ROLLBACK (SQ
8870: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32  LITE_NOTICE | (2
8880: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
8890: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54  LITE_WARNING_AUT
88a0: 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51  OINDEX       (SQ
88b0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28  LITE_WARNING | (
88c0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
88d0: 51 4c 49 54 45 5f 41 55 54 48 5f 55 53 45 52 20  QLITE_AUTH_USER 
88e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
88f0: 51 4c 49 54 45 5f 41 55 54 48 20 7c 20 28 31 3c  QLITE_AUTH | (1<
8900: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
8910: 49 54 45 5f 4f 4b 5f 4c 4f 41 44 5f 50 45 52 4d  ITE_OK_LOAD_PERM
8920: 41 4e 45 4e 54 4c 59 20 20 20 20 20 28 53 51 4c  ANENTLY     (SQL
8930: 49 54 45 5f 4f 4b 20 7c 20 28 31 3c 3c 38 29 29  ITE_OK | (1<<8))
8940: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
8950: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
8960: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
8970: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
8980: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
8990: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
89a0: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
89b0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
89c0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
89d0: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
89e0: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
89f0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
8a00: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
8a10: 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66   method..*/.#def
8a20: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8a30: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20  READONLY        
8a40: 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20   0x00000001  /* 
8a50: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
8a60: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
8a70: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8a80: 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20 20  READWRITE       
8a90: 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20   0x00000002  /* 
8aa0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
8ab0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
8ac0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8ad0: 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20 20  CREATE          
8ae0: 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20   0x00000004  /* 
8af0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
8b00: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
8b10: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8b20: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20  DELETEONCLOSE   
8b30: 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20   0x00000008  /* 
8b40: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
8b50: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8b60: 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20 20  EXCLUSIVE       
8b70: 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20   0x00000010  /* 
8b80: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
8b90: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8ba0: 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20  AUTOPROXY       
8bb0: 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20   0x00000020  /* 
8bc0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
8bd0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8be0: 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20 20  URI             
8bf0: 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20   0x00000040  /* 
8c00: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
8c10: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
8c20: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8c30: 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20  MEMORY          
8c40: 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20   0x00000080  /* 
8c50: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
8c60: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
8c70: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8c80: 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20  MAIN_DB         
8c90: 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20   0x00000100  /* 
8ca0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
8cb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8cc0: 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20  TEMP_DB         
8cd0: 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20   0x00000200  /* 
8ce0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
8cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8d00: 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20  TRANSIENT_DB    
8d10: 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20   0x00000400  /* 
8d20: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
8d30: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8d40: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  MAIN_JOURNAL    
8d50: 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20   0x00000800  /* 
8d60: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
8d70: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8d80: 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20  TEMP_JOURNAL    
8d90: 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20   0x00001000  /* 
8da0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
8db0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8dc0: 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20  SUBJOURNAL      
8dd0: 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20   0x00002000  /* 
8de0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
8df0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8e00: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20  MASTER_JOURNAL  
8e10: 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20   0x00004000  /* 
8e20: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  VFS only */.#def
8e30: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8e40: 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20 20  NOMUTEX         
8e50: 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20   0x00008000  /* 
8e60: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
8e70: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
8e80: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8e90: 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20  FULLMUTEX       
8ea0: 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20   0x00010000  /* 
8eb0: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
8ec0: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
8ed0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8ee0: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
8ef0: 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20   0x00020000  /* 
8f00: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
8f10: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
8f20: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8f30: 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20 20  PRIVATECACHE    
8f40: 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20   0x00040000  /* 
8f50: 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f  Ok for sqlite3_o
8f60: 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66  pen_v2() */.#def
8f70: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ine SQLITE_OPEN_
8f80: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  WAL             
8f90: 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20   0x00080000  /* 
8fa0: 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20  VFS only */../* 
8fb0: 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20 20  Reserved:       
8fc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8fd0: 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a    0x00F00000 */.
8fe0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
8ff0: 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74 65   Device Characte
9000: 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68  ristics.**.** Th
9010: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
9020: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20  eristics method 
9030: 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
9040: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f  io_methods].** o
9050: 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e  bject returns an
9060: 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
9070: 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68  s a vector of th
9080: 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65  ese.** bit value
9090: 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f  s expressing I/O
90a0: 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63 73   characteristics
90b0: 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f   of the mass sto
90c0: 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74  rage.** device t
90d0: 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69  hat holds the fi
90e0: 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c  le that the [sql
90f0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
9100: 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a  .** refers to..*
9110: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
9120: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
9130: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
9140: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
9150: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
9160: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
9170: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
9180: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
9190: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
91a0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
91b0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
91c0: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
91d0: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
91e0: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
91f0: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
9200: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
9210: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
9220: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
9230: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
9240: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
9250: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
9260: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
9270: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
9280: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
9290: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
92a0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
92b0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
92c0: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
92d0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
92e0: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
92f0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
9300: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
9310: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
9320: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
9330: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
9340: 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68 65  o xWrite().  The
9350: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
9360: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
9370: 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  E property means
9380: 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72   that.** after r
9390: 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20  eboot following 
93a0: 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72  a crash or power
93b0: 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20   loss, the only 
93c0: 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69  bytes in a.** fi
93d0: 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72 69  le that were wri
93e0: 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c  tten at the appl
93f0: 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69  ication level mi
9400: 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65 64  ght have changed
9410: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a  .** and that adj
9420: 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65  acent bytes, eve
9430: 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20 74  n bytes within t
9440: 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61  he same sector a
9450: 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64  re.** guaranteed
9460: 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64   to be unchanged
9470: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
9480: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
9490: 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a 20 66 6c 61  WHEN_OPEN.** fla
94a0: 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  g indicates that
94b0: 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62   a file cannot b
94c0: 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 6f  e deleted when o
94d0: 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20 53 51 4c  pen.  The.** SQL
94e0: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
94f0: 42 4c 45 20 66 6c 61 67 20 69 6e 64 69 63 61 74  BLE flag indicat
9500: 65 73 20 74 68 61 74 20 74 68 65 20 66 69 6c 65  es that the file
9510: 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61 64 2d 6f   is on.** read-o
9520: 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64 20 63 61  nly media and ca
9530: 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
9540: 65 76 65 6e 20 62 79 20 70 72 6f 63 65 73 73 65  even by processe
9550: 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65 76 61 74  s with.** elevat
9560: 65 64 20 70 72 69 76 69 6c 65 67 65 73 2e 0a 2a  ed privileges..*
9570: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9580: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20  _IOCAP_ATOMIC   
9590: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
95a0: 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65  00000001.#define
95b0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
95c0: 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20 20  OMIC512         
95d0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 0a       0x00000002.
95e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
95f0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20  OCAP_ATOMIC1K   
9600: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
9610: 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53  000004.#define S
9620: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
9630: 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  IC2K            
9640: 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23 64     0x00000008.#d
9650: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
9660: 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20  AP_ATOMIC4K     
9670: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
9680: 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0010.#define SQL
9690: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
96a0: 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  8K              
96b0: 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65 66   0x00000020.#def
96c0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
96d0: 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20  _ATOMIC16K      
96e0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
96f0: 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  40.#define SQLIT
9700: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32  E_IOCAP_ATOMIC32
9710: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  K              0
9720: 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e  x00000080.#defin
9730: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
9740: 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20  TOMIC64K        
9750: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
9760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9770: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
9780: 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30  D            0x0
9790: 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20  0000200.#define 
97a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
97b0: 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20  UENTIAL         
97c0: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a 23      0x00000400.#
97d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
97e0: 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f  CAP_UNDELETABLE_
97f0: 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30  WHEN_OPEN  0x000
9800: 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00800.#define SQ
9810: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
9820: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
9830: 20 20 30 78 30 30 30 30 31 30 30 30 0a 23 64 65    0x00001000.#de
9840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
9850: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20 20 20 20  P_IMMUTABLE     
9860: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32           0x00002
9870: 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  000../*.** CAPI3
9880: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
9890: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
98a0: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
98b0: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
98c0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
98d0: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
98e0: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
98f0: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
9900: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
9910: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
9920: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
9930: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
9940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9950: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
9960: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
9970: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
9980: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
9990: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
99a0: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
99b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
99c0: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
99d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
99e0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
99f0: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
9a00: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
9a10: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
9a20: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
9a30: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
9a40: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
9a50: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
9a60: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
9a70: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
9a80: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
9a90: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
9aa0: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
9ab0: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
9ac0: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
9ad0: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
9ae0: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
9af0: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
9b00: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
9b10: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
9b20: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
9b30: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
9b40: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
9b50: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
9b60: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
9b70: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
9b80: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
9b90: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
9ba0: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
9bb0: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
9bc0: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
9bd0: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
9be0: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
9bf0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
9c00: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
9c10: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
9c20: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
9c30: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
9c40: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
9c50: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
9c60: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
9c70: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
9c80: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
9c90: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
9ca0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
9cb0: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
9cc0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
9cd0: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
9ce0: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
9cf0: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
9d00: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
9d10: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
9d20: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
9d30: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
9d40: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
9d50: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
9d60: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
9d70: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
9d80: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
9d90: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
9da0: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
9db0: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
9dc0: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
9dd0: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
9de0: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
9df0: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
9e00: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
9e10: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
9e20: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
9e30: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
9e40: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
9e50: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
9e60: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
9e70: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
9e80: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
9e90: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
9ea0: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
9eb0: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
9ec0: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
9ed0: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
9ee0: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
9ef0: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
9f00: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
9f10: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
9f20: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
9f30: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
9f40: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
9f50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
9f60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
9f70: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
9f80: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
9f90: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
9fa0: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
9fb0: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
9fc0: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
9fd0: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
9fe0: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
9ff0: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
a000: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
a010: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
a020: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
a030: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
a040: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
a050: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
a060: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
a070: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
a080: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
a090: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
a0a0: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
a0b0: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
a0c0: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
a0d0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
a0e0: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
a0f0: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
a100: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
a110: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
a120: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
a130: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
a140: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
a150: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
a160: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
a170: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
a180: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
a190: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
a1a0: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
a1b0: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
a1c0: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
a1d0: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
a1e0: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
a1f0: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
a200: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
a210: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
a220: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
a230: 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  n] method popula
a240: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
a250: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
a260: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
a270: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
a280: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
a290: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
a2a0: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
a2b0: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
a2c0: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
a2d0: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
a2e0: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
a2f0: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
a300: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
a310: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
a320: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
a330: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
a340: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
a350: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
a360: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
a370: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73  .xOpen] method s
a380: 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ets the sqlite3_
a390: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
a3a0: 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e  ement .** to a n
a3b0: 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
a3c0: 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
a3d0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c  3_io_methods.xCl
a3e0: 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61  ose method.** ma
a3f0: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65  y be invoked eve
a400: 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n if the [sqlite
a410: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70  3_vfs.xOpen] rep
a420: 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61  orted that it fa
a430: 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e  iled.  The.** on
a440: 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e  ly way to preven
a450: 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f  t a call to xClo
a460: 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66  se following a f
a470: 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76  ailed [sqlite3_v
a480: 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20  fs.xOpen].** is 
a490: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
a4a0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73  _vfs.xOpen] to s
a4b0: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
a4c0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
a4d0: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e  ment.** to NULL.
a4e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
a4f0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79   argument to xSy
a500: 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66  nc may be one of
a510: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f   [SQLITE_SYNC_NO
a520: 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  RMAL] or.** [SQL
a530: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20  ITE_SYNC_FULL]. 
a540: 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63   The first choic
a550: 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20  e is the normal 
a560: 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20  fsync()..** The 
a570: 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73  second choice is
a580: 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c   a Mac OS X styl
a590: 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65  e fullsync.  The
a5a0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41   [SQLITE_SYNC_DA
a5b0: 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20  TAONLY].** flag 
a5c0: 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74  may be ORed in t
a5d0: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20  o indicate that 
a5e0: 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66  only the data of
a5f0: 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64   the file.** and
a600: 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e   not its inode n
a610: 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65  eeds to be synce
a620: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  d..**.** The int
a630: 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78  eger values to x
a640: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
a650: 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a  ck() are one of.
a660: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
a670: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
a680: 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
a690: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
a6a0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
a6b0: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
a6c0: 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
a6d0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
a6e0: 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
a6f0: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
a700: 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  VE]..** </ul>.**
a710: 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73   xLock() increas
a720: 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e  es the lock. xUn
a730: 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73  lock() decreases
a740: 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68   the lock..** Th
a750: 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  e xCheckReserved
a760: 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68  Lock() method ch
a770: 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79  ecks whether any
a780: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
a790: 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20  tion,.** either 
a7a0: 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  in this process 
a7b0: 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72  or in some other
a7c0: 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c   process, is hol
a7d0: 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c  ding a RESERVED,
a7e0: 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20  .** PENDING, or 
a7f0: 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f  EXCLUSIVE lock o
a800: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20  n the file.  It 
a810: 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20  returns true.** 
a820: 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65  if such a lock e
a830: 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20  xists and false 
a840: 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a  otherwise..**.**
a850: 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   The xFileContro
a860: 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20  l() method is a 
a870: 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63  generic interfac
a880: 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75  e that allows cu
a890: 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c  stom.** VFS impl
a8a0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64  ementations to d
a8b0: 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20  irectly control 
a8c0: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69  an open file usi
a8d0: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
a8e0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
a8f0: 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  )] interface.  T
a900: 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61  he second "op" a
a910: 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a  rgument is an.**
a920: 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e   integer opcode.
a930: 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
a940: 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69  ment is a generi
a950: 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64  c pointer intend
a960: 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74  ed to.** point t
a970: 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68  o a structure th
a980: 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61  at may contain a
a990: 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63  rguments or spac
a9a0: 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a  e in which to.**
a9b0: 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61   write return va
a9c0: 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c  lues.  Potential
a9d0: 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43   uses for xFileC
a9e0: 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62  ontrol() might b
a9f0: 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74  e.** functions t
aa00: 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e  o enable blockin
aa10: 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d  g locks with tim
aa20: 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65  eouts, to change
aa30: 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20   the.** locking 
aa40: 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78  strategy (for ex
aa50: 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74  ample to use dot
aa60: 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f  -file locks), to
aa70: 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75   inquire.** abou
aa80: 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20  t the status of 
aa90: 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72  a lock, or to br
aaa0: 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e  eak stale locks.
aab0: 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20    The SQLite.** 
aac0: 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c  core reserves al
aad0: 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74  l opcodes less t
aae0: 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20  han 100 for its 
aaf0: 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 66  own use..** A [f
ab00: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
ab10: 64 65 73 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70  des | list of op
ab20: 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e  codes] less than
ab30: 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c   100 is availabl
ab40: 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  e..** Applicatio
ab50: 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61  ns that define a
ab60: 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e   custom xFileCon
ab70: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75  trol method shou
ab80: 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a  ld use opcodes.*
ab90: 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  * greater than 1
aba0: 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66  00 to avoid conf
abb0: 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c  licts.  VFS impl
abc0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
abd0: 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
abe0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66  LITE_NOTFOUND] f
abf0: 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  or file control 
ac00: 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65  opcodes that the
ac10: 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f  y do not.** reco
ac20: 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  gnize..**.** The
ac30: 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d   xSectorSize() m
ac40: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68  ethod returns th
ac50: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66  e sector size of
ac60: 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74   the.** device t
ac70: 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68  hat underlies th
ac80: 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63  e file.  The sec
ac90: 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a  tor size is the.
aca0: 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65  ** minimum write
acb0: 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72   that can be per
acc0: 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64  formed without d
acd0: 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68  isturbing.** oth
ace0: 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  er bytes in the 
acf0: 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69  file.  The xDevi
ad00: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
ad10: 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65  s().** method re
ad20: 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74  turns a bit vect
ad30: 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65  or describing be
ad40: 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a  haviors of the.*
ad50: 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76  * underlying dev
ad60: 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ice:.**.** <ul>.
ad70: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
ad80: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a  IOCAP_ATOMIC].**
ad90: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
ada0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a  CAP_ATOMIC512].*
adb0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
adc0: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a  OCAP_ATOMIC1K].*
add0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
ade0: 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a  OCAP_ATOMIC2K].*
adf0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
ae00: 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a  OCAP_ATOMIC4K].*
ae10: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
ae20: 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a  OCAP_ATOMIC8K].*
ae30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
ae40: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a  OCAP_ATOMIC16K].
ae50: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
ae60: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d  IOCAP_ATOMIC32K]
ae70: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
ae80: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
ae90: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
aea0: 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50  E_IOCAP_SAFE_APP
aeb0: 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  END].** <li> [SQ
aec0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
aed0: 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  NTIAL].** <li> [
aee0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
aef0: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
af00: 45 4e 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  EN].** <li> [SQL
af10: 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53  ITE_IOCAP_POWERS
af20: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 0a 2a  AFE_OVERWRITE].*
af30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
af40: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 5d 0a  OCAP_IMMUTABLE].
af50: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
af60: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
af70: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
af80: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
af90: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
afa0: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
afb0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
afc0: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
afd0: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
afe0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
aff0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
b000: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
b010: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
b020: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
b030: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
b040: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
b050: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
b060: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
b070: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
b080: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
b090: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
b0a0: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
b0b0: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
b0c0: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
b0d0: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
b0e0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
b0f0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
b100: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
b110: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
b120: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
b130: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
b140: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
b150: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
b160: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
b170: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
b180: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
b190: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
b1a0: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
b1b0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
b1c0: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
b1d0: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
b1e0: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
b1f0: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
b200: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
b210: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
b220: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
b230: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
b240: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
b250: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
b260: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
b270: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
b280: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
b290: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
b2a0: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
b2b0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
b2c0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
b2d0: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
b2e0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
b2f0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
b300: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
b310: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
b320: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
b330: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
b340: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
b350: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
b360: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
b370: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
b380: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
b390: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
b3a0: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
b3b0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
b3c0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
b3d0: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
b3e0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
b3f0: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
b400: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
b410: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
b420: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
b430: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
b440: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
b450: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
b460: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
b470: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
b480: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
b490: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
b4a0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
b4b0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
b4c0: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
b4d0: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
b4e0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
b4f0: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
b500: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
b510: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
b520: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
b530: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
b540: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
b550: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
b560: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
b570: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
b580: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
b590: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
b5a0: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
b5b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
b5c0: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
b5d0: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
b5e0: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
b5f0: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
b600: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
b610: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
b620: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
b630: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
b640: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
b650: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
b660: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
b670: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
b680: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
b690: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
b6a0: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
b6b0: 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73   int (*xFetch)(s
b6c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
b6d0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
b6e0: 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69  t, int iAmt, voi
b6f0: 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28  d **pp);.  int (
b700: 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74  *xUnfetch)(sqlit
b710: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
b720: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76  3_int64 iOfst, v
b730: 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65  oid *p);.  /* Me
b740: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
b750: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
b760: 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 3 */.  /* Addi
b770: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
b780: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
b790: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
b7a0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
b7b0: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
b7c0: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
b7d0: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
b7e0: 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f   {file control o
b7f0: 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f  pcodes} {file co
b800: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a  ntrol opcode}.**
b810: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
b820: 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  r constants are 
b830: 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20  opcodes for the 
b840: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
b850: 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  hod.** of the [s
b860: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
b870: 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f  s] object and fo
b880: 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  r the [sqlite3_f
b890: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a  ile_control()].*
b8a0: 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  * interface..**.
b8b0: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b  ** <ul>.** <li>[
b8c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
b8d0: 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65  CKSTATE]].** The
b8e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
b8f0: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
b900: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
b910: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
b920: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
b930: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
b940: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
b950: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
b960: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
b970: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
b980: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
b990: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
b9a0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
b9b0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
b9c0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
b9d0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
b9e0: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
b9f0: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
ba00: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
ba10: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
ba20: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
ba30: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
ba40: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
ba50: 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  and is only avai
ba60: 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53  lable when the S
ba70: 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f  QLITE_TEST.** co
ba80: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
ba90: 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
baa0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
bab0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a  NTL_SIZE_HINT]].
bac0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
bad0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20  CNTL_SIZE_HINT] 
bae0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62  opcode is used b
baf0: 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65  y SQLite to give
bb00: 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65   the VFS.** laye
bb10: 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20  r a hint of how 
bb20: 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61  large the databa
bb30: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f  se file will gro
bb40: 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74  w to be during t
bb50: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72  he.** current tr
bb60: 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73  ansaction.  This
bb70: 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61   hint is not gua
bb80: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63  ranteed to be ac
bb90: 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a  curate but it.**
bba0: 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e   is often close.
bbb0: 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67    The underlying
bbc0: 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73   VFS might choos
bbd0: 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65  e to preallocate
bbe0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
bbf0: 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e  e space based on
bc00: 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72   this hint in or
bc10: 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74  der to help writ
bc20: 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  es to the databa
bc30: 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66  se.** file run f
bc40: 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  aster..**.** <li
bc50: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
bc60: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  CHUNK_SIZE]].** 
bc70: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
bc80: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
bc90: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
bca0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
bcb0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
bcc0: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
bcd0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
bce0: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
bcf0: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
bd00: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
bd10: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
bd20: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
bd30: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
bd40: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
bd50: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
bd60: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
bd70: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
bd80: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
bd90: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
bda0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
bdb0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
bdc0: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
bdd0: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
bde0: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
bdf0: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
be00: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
be10: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
be20: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
be30: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
be40: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ms..**.** <li>[[
be50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
be60: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  E_POINTER]].** T
be70: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
be80: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f  _FILE_POINTER] o
be90: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
bea0: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
beb0: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
bec0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
bed0: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
bee0: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
bef0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
bf00: 63 74 69 6f 6e 2e 20 20 53 65 65 20 61 6c 73 6f  ction.  See also
bf10: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a   [SQLITE_FCNTL_J
bf20: 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d 2e  OURNAL_POINTER].
bf30: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
bf40: 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41  ITE_FCNTL_JOURNA
bf50: 4c 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  L_POINTER]].** T
bf60: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
bf70: 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52  _JOURNAL_POINTER
bf80: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
bf90: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
bfa0: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
bfb0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
bfc0: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
bfd0: 77 69 74 68 20 74 68 65 20 6a 6f 75 72 6e 61 6c  with the journal
bfe0: 20 66 69 6c 65 20 28 65 69 74 68 65 72 0a 2a 2a   file (either.**
bff0: 20 74 68 65 20 5b 72 6f 6c 6c 62 61 63 6b 20 6a   the [rollback j
c000: 6f 75 72 6e 61 6c 5d 20 6f 72 20 74 68 65 20 5b  ournal] or the [
c010: 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 5d  write-ahead log]
c020: 29 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ) for a particul
c030: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
c040: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
c050: 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46 43 4e  also [SQLITE_FCN
c060: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
c070: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
c080: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
c090: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20  OMITTED]].** No 
c0a0: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a  longer in use..*
c0b0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c0c0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a  E_FCNTL_SYNC]].*
c0d0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
c0e0: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65  NTL_SYNC] opcode
c0f0: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
c100: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
c110: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74  te and.** sent t
c120: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69  o the VFS immedi
c130: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65  ately before the
c140: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
c150: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a   invoked on a.**
c160: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
c170: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69  escriptor. Or, i
c180: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
c190: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  od is not invoke
c1a0: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68  d .** because th
c1b0: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69  e user has confi
c1c0: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74  gured SQLite wit
c1d0: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79  h .** [PRAGMA sy
c1e0: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
c1f0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
c200: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  FF] it is invoke
c210: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f  d in place .** o
c220: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
c230: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65  od. In most case
c240: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61  s, the pointer a
c250: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77  rgument passed w
c260: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65  ith.** this file
c270: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c  -control is NULL
c280: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
c290: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
c2a0: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a  is being synced.
c2b0: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20  ** as part of a 
c2c0: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63  multi-database c
c2d0: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d  ommit, the argum
c2e0: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
c2f0: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
c300: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
c310: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74  ing the transact
c320: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72  ions master-jour
c330: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56  nal file name. V
c340: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f  FSes that .** do
c350: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
c360: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c  ignal should sil
c370: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
c380: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
c390: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c  ations .** shoul
c3a0: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
c3b0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
c3c0: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
c3d0: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
c3e0: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74   may .** disrupt
c3f0: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
c400: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
c410: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
c420: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
c430: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c440: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
c450: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20  ASETWO]].** The 
c460: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
c470: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f  MMIT_PHASETWO] o
c480: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
c490: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
c4a0: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73   SQLite.** and s
c4b0: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61  ent to the VFS a
c4c0: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  fter a transacti
c4d0: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d  on has been comm
c4e0: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  itted immediatel
c4f0: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20  y.** but before 
c500: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
c510: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20  unlocked. VFSes 
c520: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64  that do not need
c530: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20   this signal.** 
c540: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
c550: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
c560: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
c570: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
c580: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
c590: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
c5a0: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
c5b0: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
c5c0: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70  srupt the .** op
c5d0: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
c5e0: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
c5f0: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
c600: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
c610: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c620: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
c630: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
c640: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
c650: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
c660: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
c670: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
c680: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
c690: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
c6a0: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
c6b0: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
c6c0: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
c6d0: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
c6e0: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
c6f0: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
c700: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
c710: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
c720: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
c730: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
c740: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
c750: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
c760: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
c770: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
c780: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
c790: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
c7a0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
c7b0: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
c7c0: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
c7d0: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
c7e0: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
c7f0: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
c800: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
c810: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
c820: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
c830: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
c840: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
c850: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
c860: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
c870: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
c880: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
c890: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
c8a0: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
c8b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
c8c0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
c8d0: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
c8e0: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
c8f0: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
c900: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
c910: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
c920: 73 74 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  st integer is th
c930: 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e  e new retry coun
c940: 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
c950: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74  .** integer is t
c960: 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69  he delay.  If ei
c970: 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20  ther integer is 
c980: 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
c990: 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73  he setting.** is
c9a0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74   not changed but
c9b0: 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69   instead the pri
c9c0: 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  or value of that
c9d0: 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74   setting is writ
c9e0: 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20  ten.** into the 
c9f0: 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c  array entry, all
ca00: 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e  owing the curren
ca10: 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73  t retry settings
ca20: 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72   to be.** interr
ca30: 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62  ogated.  The zDb
ca40: 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  Name parameter i
ca50: 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
ca60: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ca70: 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d  NTL_PERSIST_WAL]
ca80: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
ca90: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
caa0: 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  WAL] opcode is u
cab0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
cac0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
cad0: 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69  stent [WAL | Wri
cae0: 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65  te Ahead Log] se
caf0: 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75  tting.  By defau
cb00: 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72  lt, the auxiliar
cb10: 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64  y.** write ahead
cb20: 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20   log and shared 
cb30: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65  memory files use
cb40: 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f  d for transactio
cb50: 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65  n control.** are
cb60: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
cb70: 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20  eleted when the 
cb80: 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f  latest connectio
cb90: 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  n to the databas
cba0: 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65  e.** closes.  Se
cbb0: 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74  tting persistent
cbc0: 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73   WAL mode causes
cbd0: 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20   those files to 
cbe0: 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a  persist after.**
cbf0: 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74   close.  Persist
cc00: 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73  ing the files is
cc10: 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68   useful when oth
cc20: 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61  er processes tha
cc30: 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65  t do not.** have
cc40: 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f   write permissio
cc50: 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f  n on the directo
cc60: 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ry containing th
cc70: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
cc80: 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20  want.** to read 
cc90: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
cca0: 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e  e, as the WAL an
ccb0: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
ccc0: 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74  files must exist
ccd0: 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72  .** in order for
cce0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f   the database to
ccf0: 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54   be readable.  T
cd00: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
cd10: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
cd20: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
cd30: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
cd40: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
cd50: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
cd60: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
cd70: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
cd80: 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  sable persistent
cd90: 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74   WAL mode or 1 t
cda0: 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74  o enable persist
cdb0: 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e  ent.** WAL mode.
cdc0: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
cdd0: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
cde0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
cdf0: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
ce00: 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e  ** WAL persisten
ce10: 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  ce setting..**.*
ce20: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ce30: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
ce40: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
ce50: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
ce60: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
ce70: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
ce80: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
ce90: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
cea0: 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66  istent "powersaf
ceb0: 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20  e-overwrite" or 
cec0: 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20  "PSOW" setting. 
ced0: 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e   The PSOW settin
cee0: 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20  g.** determines 
cef0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  the [SQLITE_IOCA
cf00: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
cf10: 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68  WRITE] bit of th
cf20: 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72  e.** xDeviceChar
cf30: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
cf40: 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ods. The fourth 
cf50: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
cf60: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
cf70: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
cf80: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
cf90: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
cfa0: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
cfb0: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
cfc0: 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f   to disable zero
cfd0: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20  -damage mode or 
cfe0: 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f  1 to enable zero
cff0: 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e  -damage.** mode.
d000: 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72    If the integer
d010: 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20   is -1, then it 
d020: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
d030: 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ith the current.
d040: 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  ** zero-damage m
d050: 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  ode setting..**.
d060: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
d070: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d  FCNTL_OVERWRITE]
d080: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
d090: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
d0a0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76  E] opcode is inv
d0b0: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  oked by SQLite a
d0c0: 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20  fter opening.** 
d0d0: 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74  a write transact
d0e0: 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20  ion to indicate 
d0f0: 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20  that, unless it 
d100: 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66  is rolled back f
d110: 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f  or some.** reaso
d120: 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61  n, the entire da
d130: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
d140: 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20   be overwritten 
d150: 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a  by the current .
d160: 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  ** transaction. 
d170: 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20  This is used by 
d180: 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e  VACUUM operation
d190: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
d1a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
d1b0: 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  AME]].** ^The [S
d1c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
d1d0: 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20  AME] opcode can 
d1e0: 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
d1f0: 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a  n the names of.*
d200: 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e  * all [VFSes] in
d210: 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20   the VFS stack. 
d220: 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f   The names are o
d230: 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20  f all VFS shims 
d240: 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c  and the.** final
d250: 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46   bottom-level VF
d260: 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e  S are written in
d270: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
d280: 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
d290: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61  ite3_malloc()] a
d2a0: 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  nd the result is
d2b0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63   stored in the c
d2c0: 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a  har* variable.**
d2d0: 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68   that the fourth
d2e0: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73   parameter of [s
d2f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
d300: 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f  rol()] points to
d310: 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20  ..** The caller 
d320: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
d330: 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d  or freeing the m
d340: 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e  emory when done.
d350: 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c    As with.** all
d360: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63   file-control ac
d370: 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20  tions, there is 
d380: 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61  no guarantee tha
d390: 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75  t this will actu
d3a0: 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68  ally.** do anyth
d3b0: 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68  ing.  Callers sh
d3c0: 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20  ould initialize 
d3d0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
d3e0: 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20  le to a NULL.** 
d3f0: 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20  pointer in case 
d400: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
d410: 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  l is not impleme
d420: 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65  nted.  This file
d430: 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69  -control.** is i
d440: 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67  ntended for diag
d450: 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e  nostic use only.
d460: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d470: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f  ITE_FCNTL_VFS_PO
d480: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  INTER]].** ^The 
d490: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
d4a0: 53 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  S_POINTER] opcod
d4b0: 65 20 66 69 6e 64 73 20 61 20 70 6f 69 6e 74 65  e finds a pointe
d4c0: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
d4d0: 65 6c 0a 2a 2a 20 5b 56 46 53 65 73 5d 20 63 75  el.** [VFSes] cu
d4e0: 72 72 65 6e 74 6c 79 20 69 6e 20 75 73 65 2e 20  rrently in use. 
d4f0: 20 5e 28 54 68 65 20 61 72 67 75 6d 65 6e 74 20   ^(The argument 
d500: 58 20 69 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  X in.** sqlite3_
d510: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 64 62 2c  file_control(db,
d520: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
d530: 5f 50 4f 49 4e 54 45 52 2c 58 29 20 6d 75 73 74  _POINTER,X) must
d540: 20 62 65 0a 2a 2a 20 6f 66 20 74 79 70 65 20 22   be.** of type "
d550: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 2a 2a  [sqlite3_vfs] **
d560: 22 2e 20 20 54 68 69 73 20 6f 70 63 6f 64 65 73  ".  This opcodes
d570: 20 77 69 6c 6c 20 73 65 74 20 2a 58 0a 2a 2a 20   will set *X.** 
d580: 74 6f 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  to a pointer to 
d590: 74 68 65 20 74 6f 70 2d 6c 65 76 65 6c 20 56 46  the top-level VF
d5a0: 53 2e 29 5e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  S.)^.** ^When th
d5b0: 65 72 65 20 61 72 65 20 6d 75 6c 74 69 70 6c 65  ere are multiple
d5c0: 20 56 46 53 20 73 68 69 6d 73 20 69 6e 20 74 68   VFS shims in th
d5d0: 65 20 73 74 61 63 6b 2c 20 74 68 69 73 20 6f 70  e stack, this op
d5e0: 63 6f 64 65 20 66 69 6e 64 73 20 74 68 65 0a 2a  code finds the.*
d5f0: 2a 20 75 70 70 65 72 2d 6d 6f 73 74 20 73 68 69  * upper-most shi
d600: 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  m only..**.** <l
d610: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
d620: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
d630: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
d640: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
d650: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
d660: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
d670: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
d680: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
d690: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
d6a0: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
d6b0: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
d6c0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
d6d0: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
d6e0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
d6f0: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
d700: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
d710: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
d720: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
d730: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
d740: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
d750: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
d760: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
d770: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
d780: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
d790: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
d7a0: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
d7b0: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
d7c0: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
d7d0: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
d7e0: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
d7f0: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
d800: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
d810: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
d820: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
d830: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
d840: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
d850: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
d860: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
d870: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
d880: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
d890: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
d8a0: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
d8b0: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
d8c0: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
d8d0: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
d8e0: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
d8f0: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
d900: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
d910: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
d920: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
d930: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
d940: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
d950: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
d960: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
d970: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
d980: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
d990: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
d9a0: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
d9b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
d9c0: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
d9d0: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
d9e0: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
d9f0: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
da00: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
da10: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
da20: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
da30: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
da40: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
da50: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
da60: 65 6e 74 20 69 66 20 72 65 73 75 6c 74 20 73 74  ent if result st
da70: 72 69 6e 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72  ring is NULL, or
da80: 20 74 68 61 74 20 72 65 74 75 72 6e 73 20 61 20   that returns a 
da90: 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72  copy.** of the r
daa0: 65 73 75 6c 74 20 73 74 72 69 6e 67 20 69 66 20  esult string if 
dab0: 74 68 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  the string is no
dac0: 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74  n-NULL..** ^If t
dad0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
dae0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
daf0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a  ntrol returns.**
db00: 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65   any result code
db10: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
db20: 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49  ITE_OK] or [SQLI
db30: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
db40: 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  at means.** that
db50: 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74   the VFS encount
db60: 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68  ered an error wh
db70: 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65  ile handling the
db80: 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68   [PRAGMA] and th
db90: 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e  e.** compilation
dba0: 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20 66   of the PRAGMA f
dbb0: 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72  ails with an err
dbc0: 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  or.  ^The [SQLIT
dbd0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
dbe0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
dbf0: 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62 65  occurs at the be
dc00: 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d  ginning of pragm
dc10: 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c  a statement anal
dc20: 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69  ysis and so.** i
dc30: 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65  t is able to ove
dc40: 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b  rride built-in [
dc50: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
dc60: 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ts..**.** <li>[[
dc70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
dc80: 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54  YHANDLER]].** ^T
dc90: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
dca0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a  _BUSYHANDLER].**
dcb0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61   file-control ma
dcc0: 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79 20  y be invoked by 
dcd0: 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64 61  SQLite on the da
dce0: 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e 64  tabase file hand
dcf0: 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66  le.** shortly af
dd00: 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65 64  ter it is opened
dd10: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f   in order to pro
dd20: 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56 46  vide a custom VF
dd30: 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a 2a  S with access.**
dd40: 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74 69   to the connecti
dd50: 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  ons busy-handler
dd60: 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61   callback. The a
dd70: 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74 79  rgument is of ty
dd80: 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20  pe (void **).** 
dd90: 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  - an array of tw
dda0: 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75 65  o (void *) value
ddb0: 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76 6f  s. The first (vo
ddc0: 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20 70  id *) actually p
ddd0: 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75  oints.** to a fu
dde0: 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 28  nction of type (
ddf0: 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29 29  int (*)(void *))
de00: 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  . In order to in
de10: 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63 74  voke the connect
de20: 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e  ions.** busy-han
de30: 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63 74  dler, this funct
de40: 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69 6e  ion should be in
de50: 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20 73  voked with the s
de60: 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20 69  econd (void *) i
de70: 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20 61  n.** the array a
de80: 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d  s the only argum
de90: 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75 72  ent. If it retur
dea0: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
deb0: 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  n the operation.
dec0: 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
ded0: 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74 75  ried. If it retu
dee0: 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63 75  rns zero, the cu
def0: 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64 20  stom VFS should 
df00: 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63  abandon the.** c
df10: 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e  urrent operation
df20: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
df30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
df40: 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70  ILENAME]].** ^Ap
df50: 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e  plication can in
df60: 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c 49 54 45  voke the [SQLITE
df70: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
df80: 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  AME] file-contro
df90: 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20 53 51 4c  l.** to have SQL
dfa0: 69 74 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a  ite generate a.*
dfb0: 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
dfc0: 6e 61 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  name using the s
dfd0: 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68  ame algorithm th
dfe0: 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74  at is followed t
dff0: 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65  o generate.** te
e000: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
e010: 73 20 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65  s for TEMP table
e020: 73 20 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65  s and other inte
e030: 72 6e 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a  rnal uses.  The.
e040: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
e050: 6c 64 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77  ld be a char** w
e060: 68 69 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c  hich will be fil
e070: 6c 65 64 20 77 69 74 68 20 74 68 65 20 66 69 6c  led with the fil
e080: 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e  ename.** written
e090: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
e0a0: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
e0b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20  te3_malloc()].  
e0c0: 54 68 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c  The caller shoul
e0d0: 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  d.** invoke [sql
e0e0: 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20  ite3_free()] on 
e0f0: 74 68 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76  the result to av
e100: 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61  oid a memory lea
e110: 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  k..**.** <li>[[S
e120: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
e130: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
e140: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
e150: 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
e160: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 74 6f 20  trol is used to 
e170: 71 75 65 72 79 20 6f 72 20 73 65 74 20 74 68 65  query or set the
e180: 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  .** maximum numb
e190: 65 72 20 6f 66 20 62 79 74 65 73 20 74 68 61 74  er of bytes that
e1a0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 66 6f   will be used fo
e1b0: 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20  r memory-mapped 
e1c0: 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  I/O..** The argu
e1d0: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
e1e0: 72 20 74 6f 20 61 20 76 61 6c 75 65 20 6f 66 20  r to a value of 
e1f0: 74 79 70 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  type sqlite3_int
e200: 36 34 20 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e  64 that.** is an
e210: 20 61 64 76 69 73 6f 72 79 20 6d 61 78 69 6d 75   advisory maximu
e220: 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  m number of byte
e230: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 20 74 6f  s in the file to
e240: 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68   memory map.  Th
e250: 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 73 20  e.** pointer is 
e260: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
e270: 20 74 68 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20   the old value. 
e280: 20 54 68 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f   The limit is no
e290: 74 20 63 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20  t changed if.** 
e2a0: 74 68 65 20 76 61 6c 75 65 20 6f 72 69 67 69 6e  the value origin
e2b0: 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20 74 6f 20  ally pointed to 
e2c0: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 61 6e 64  is negative, and
e2d0: 20 73 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   so the current 
e2e0: 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65  limit .** can be
e2f0: 20 71 75 65 72 69 65 64 20 62 79 20 70 61 73 73   queried by pass
e300: 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e 74 65 72  ing in a pointer
e310: 20 74 6f 20 61 20 6e 65 67 61 74 69 76 65 20 6e   to a negative n
e320: 75 6d 62 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20  umber.  This.** 
e330: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20  file-control is 
e340: 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
e350: 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52  to implement [PR
e360: 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e  AGMA mmap_size].
e370: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
e380: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
e390: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
e3a0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69  _FCNTL_TRACE] fi
e3b0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69  le control provi
e3c0: 64 65 73 20 61 64 76 69 73 6f 72 79 20 69 6e 66  des advisory inf
e3d0: 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74  ormation.** to t
e3e0: 68 65 20 56 46 53 20 61 62 6f 75 74 20 77 68 61  he VFS about wha
e3f0: 74 20 74 68 65 20 68 69 67 68 65 72 20 6c 61 79  t the higher lay
e400: 65 72 73 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ers of the SQLit
e410: 65 20 73 74 61 63 6b 20 61 72 65 20 64 6f 69 6e  e stack are doin
e420: 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20  g..** This file 
e430: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
e440: 62 79 20 73 6f 6d 65 20 56 46 53 20 61 63 74 69  by some VFS acti
e450: 76 69 74 79 20 74 72 61 63 69 6e 67 20 5b 73 68  vity tracing [sh
e460: 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67  ims]..** The arg
e470: 75 6d 65 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d  ument is a zero-
e480: 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
e490: 67 2e 20 20 48 69 67 68 65 72 20 6c 61 79 65 72  g.  Higher layer
e4a0: 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69  s in the.** SQLi
e4b0: 74 65 20 73 74 61 63 6b 20 6d 61 79 20 67 65 6e  te stack may gen
e4c0: 65 72 61 74 65 20 69 6e 73 74 61 6e 63 65 73 20  erate instances 
e4d0: 6f 66 20 74 68 69 73 20 66 69 6c 65 20 63 6f 6e  of this file con
e4e0: 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b  trol if.** the [
e4f0: 53 51 4c 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c  SQLITE_USE_FCNTL
e500: 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d  _TRACE] compile-
e510: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65  time option is e
e520: 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  nabled..**.** <l
e530: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
e540: 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20  _HAS_MOVED]].** 
e550: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
e560: 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c  L_HAS_MOVED] fil
e570: 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70  e control interp
e580: 72 65 74 73 20 69 74 73 20 61 72 67 75 6d 65 6e  rets its argumen
e590: 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  t as a.** pointe
e5a0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
e5b0: 61 6e 64 20 69 74 20 77 72 69 74 65 73 20 61 20  and it writes a 
e5c0: 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61  boolean into tha
e5d0: 74 20 69 6e 74 65 67 65 72 20 64 65 70 65 6e 64  t integer depend
e5e0: 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  ing.** on whethe
e5f0: 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 66 69 6c  r or not the fil
e600: 65 20 68 61 73 20 62 65 65 6e 20 72 65 6e 61 6d  e has been renam
e610: 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65  ed, moved, or de
e620: 6c 65 74 65 64 20 73 69 6e 63 65 20 69 74 0a 2a  leted since it.*
e630: 2a 20 77 61 73 20 66 69 72 73 74 20 6f 70 65 6e  * was first open
e640: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
e650: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
e660: 33 32 5f 47 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_GET_HANDLE]].
e670: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
e680: 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48  CNTL_WIN32_GET_H
e690: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 63 61  ANDLE] opcode ca
e6a0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
e6b0: 61 69 6e 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72  ain the.** under
e6c0: 6c 79 69 6e 67 20 6e 61 74 69 76 65 20 66 69 6c  lying native fil
e6d0: 65 20 68 61 6e 64 6c 65 20 61 73 73 6f 63 69 61  e handle associa
e6e0: 74 65 64 20 77 69 74 68 20 61 20 66 69 6c 65 20  ted with a file 
e6f0: 68 61 6e 64 6c 65 2e 20 20 54 68 69 73 20 66 69  handle.  This fi
e700: 6c 65 0a 2a 2a 20 63 6f 6e 74 72 6f 6c 20 69 6e  le.** control in
e710: 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67  terprets its arg
e720: 75 6d 65 6e 74 20 61 73 20 61 20 70 6f 69 6e 74  ument as a point
e730: 65 72 20 74 6f 20 61 20 6e 61 74 69 76 65 20 66  er to a native f
e740: 69 6c 65 20 68 61 6e 64 6c 65 20 61 6e 64 0a 2a  ile handle and.*
e750: 2a 20 77 72 69 74 65 73 20 74 68 65 20 72 65 73  * writes the res
e760: 75 6c 74 69 6e 67 20 76 61 6c 75 65 20 74 68 65  ulting value the
e770: 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  re..**.** <li>[[
e780: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
e790: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a  32_SET_HANDLE]].
e7a0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
e7b0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
e7c0: 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73  ANDLE] opcode is
e7d0: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
e7e0: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
e7f0: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
e800: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
e810: 68 6f 64 20 74 6f 20 73 77 61 70 20 74 68 65 20  hod to swap the 
e820: 66 69 6c 65 20 68 61 6e 64 6c 65 20 77 69 74 68  file handle with
e830: 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e   the one.** poin
e840: 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 70 41  ted to by the pA
e850: 72 67 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68  rg argument.  Th
e860: 69 73 20 63 61 70 61 62 69 6c 69 74 79 20 69 73  is capability is
e870: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
e880: 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79  ting.** and only
e890: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
e8a0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
e8b0: 54 45 5f 54 45 53 54 20 69 73 20 64 65 66 69 6e  TE_TEST is defin
e8c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
e8d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c  SQLITE_FCNTL_WAL
e8e0: 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20  _BLOCK]].** The 
e8f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41  [SQLITE_FCNTL_WA
e900: 4c 5f 42 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69  L_BLOCK] is a si
e910: 67 6e 61 6c 20 74 6f 20 74 68 65 20 56 46 53 20  gnal to the VFS 
e920: 6c 61 79 65 72 20 74 68 61 74 20 69 74 20 6d 69  layer that it mi
e930: 67 68 74 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74  ght.** be advant
e940: 61 67 65 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20  ageous to block 
e950: 6f 6e 20 74 68 65 20 6e 65 78 74 20 57 41 4c 20  on the next WAL 
e960: 6c 6f 63 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b  lock if the lock
e970: 20 69 73 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74   is not immediat
e980: 65 6c 79 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65  ely.** available
e990: 2e 20 20 54 68 65 20 57 41 4c 20 73 75 62 73 79  .  The WAL subsy
e9a0: 73 74 65 6d 20 69 73 73 75 65 73 20 74 68 69 73  stem issues this
e9b0: 20 73 69 67 6e 61 6c 20 64 75 72 69 6e 67 20 72   signal during r
e9c0: 61 72 65 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61  are.** circumsta
e9d0: 6e 63 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f  nces in order to
e9e0: 20 66 69 78 20 61 20 70 72 6f 62 6c 65 6d 20 77   fix a problem w
e9f0: 69 74 68 20 70 72 69 6f 72 69 74 79 20 69 6e 76  ith priority inv
ea00: 65 72 73 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69  ersion..** Appli
ea10: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c  cations should <
ea20: 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20  em>not</em> use 
ea30: 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  this file-contro
ea40: 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  l..**.** <li>[[S
ea50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56  QLITE_FCNTL_ZIPV
ea60: 46 53 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  FS]].** The [SQL
ea70: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
ea80: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c  ] opcode is impl
ea90: 65 6d 65 6e 74 65 64 20 62 79 20 7a 69 70 76 66  emented by zipvf
eaa0: 73 20 6f 6e 6c 79 2e 20 41 6c 6c 20 6f 74 68 65  s only. All othe
eab0: 72 0a 2a 2a 20 56 46 53 20 73 68 6f 75 6c 64 20  r.** VFS should 
eac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f  return SQLITE_NO
ead0: 54 46 4f 55 4e 44 20 66 6f 72 20 74 68 69 73 20  TFOUND for this 
eae0: 6f 70 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  opcode..**.** <l
eaf0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
eb00: 5f 52 42 55 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  _RBU]].** The [S
eb10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
eb20: 20 6f 70 63 6f 64 65 20 69 73 20 69 6d 70 6c 65   opcode is imple
eb30: 6d 65 6e 74 65 64 20 62 79 20 74 68 65 20 73 70  mented by the sp
eb40: 65 63 69 61 6c 20 56 46 53 20 75 73 65 64 20 62  ecial VFS used b
eb50: 79 0a 2a 2a 20 74 68 65 20 52 42 55 20 65 78 74  y.** the RBU ext
eb60: 65 6e 73 69 6f 6e 20 6f 6e 6c 79 2e 20 20 41 6c  ension only.  Al
eb70: 6c 20 6f 74 68 65 72 20 56 46 53 20 73 68 6f 75  l other VFS shou
eb80: 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  ld return SQLITE
eb90: 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 0a 2a 2a  _NOTFOUND for.**
eba0: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 20 0a   this opcode.  .
ebb0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </ul>.*/.#def
ebc0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
ebd0: 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20  _LOCKSTATE      
ebe0: 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69           1.#defi
ebf0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
ec00: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
ec10: 45 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  E       2.#defin
ec20: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
ec30: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
ec40: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
ec50: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
ec60: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
ec70: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
ec80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
ec90: 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20  E_HINT          
eca0: 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
ecb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
ecc0: 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  K_SIZE          
ecd0: 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51      6.#define SQ
ece0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f  LITE_FCNTL_FILE_
ecf0: 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20  POINTER         
ed00: 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
ed10: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
ed20: 4d 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20  MITTED          
ed30: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
ed40: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
ed50: 56 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20  V_RETRY         
ed60: 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   9.#define SQLIT
ed70: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
ed80: 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31  WAL            1
ed90: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
eda0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
edb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31                11
edc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
edd0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20  FCNTL_VFSNAME   
ede0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a               12.
edf0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ee00: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
ee10: 56 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23  VERWRITE    13.#
ee20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ee30: 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20  NTL_PRAGMA      
ee40: 20 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64             14.#d
ee50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ee60: 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20  TL_BUSYHANDLER  
ee70: 20 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65            15.#de
ee80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
ee90: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20  L_TEMPFILENAME  
eea0: 20 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66           16.#def
eeb0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
eec0: 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20  _MMAP_SIZE      
eed0: 20 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69          18.#defi
eee0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
eef0: 54 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20  TRACE           
ef00: 20 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e         19.#defin
ef10: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48  e SQLITE_FCNTL_H
ef20: 41 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20  AS_MOVED        
ef30: 20 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65        20.#define
ef40: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
ef50: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20  NC              
ef60: 20 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20       21.#define 
ef70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
ef80: 4d 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20  MIT_PHASETWO    
ef90: 20 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53      22.#define S
efa0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
efb0: 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20  2_SET_HANDLE    
efc0: 20 20 20 32 33 0a 23 64 65 66 69 6e 65 20 53 51     23.#define SQ
efd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
efe0: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
eff0: 20 20 32 34 0a 23 64 65 66 69 6e 65 20 53 51 4c    24.#define SQL
f000: 49 54 45 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53  ITE_FCNTL_ZIPVFS
f010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
f020: 20 32 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   25.#define SQLI
f030: 54 45 5f 46 43 4e 54 4c 5f 52 42 55 20 20 20 20  TE_FCNTL_RBU    
f040: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
f050: 32 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  26.#define SQLIT
f060: 45 5f 46 43 4e 54 4c 5f 56 46 53 5f 50 4f 49 4e  E_FCNTL_VFS_POIN
f070: 54 45 52 20 20 20 20 20 20 20 20 20 20 20 20 32  TER            2
f080: 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
f090: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
f0a0: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 32 38  OINTER        28
f0b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f0c0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 47 45 54 5f  FCNTL_WIN32_GET_
f0d0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 39 0a  HANDLE       29.
f0e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
f0f0: 43 4e 54 4c 5f 50 44 42 20 20 20 20 20 20 20 20  CNTL_PDB        
f100: 20 20 20 20 20 20 20 20 20 20 20 20 33 30 0a 0a              30..
f110: 2f 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61  /* deprecated na
f120: 6d 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mes */.#define S
f130: 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52  QLITE_GET_LOCKPR
f140: 4f 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c  OXYFILE      SQL
f150: 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f  ITE_FCNTL_GET_LO
f160: 43 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66  CKPROXYFILE.#def
f170: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
f180: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
f190: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53    SQLITE_FCNTL_S
f1a0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
f1b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f1c0: 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20  LAST_ERRNO      
f1d0: 20 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43         SQLITE_FC
f1e0: 4e 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a  NTL_LAST_ERRNO..
f1f0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f200: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
f210: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
f220: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
f230: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
f240: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
f250: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
f260: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
f270: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
f280: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
f290: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
f2a0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
f2b0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
f2c0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
f2d0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
f2e0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
f2f0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
f300: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
f310: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
f320: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
f330: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
f340: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
f350: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
f360: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
f370: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
f380: 49 33 52 45 46 3a 20 4c 6f 61 64 61 62 6c 65 20  I3REF: Loadable 
f390: 45 78 74 65 6e 73 69 6f 6e 20 54 68 75 6e 6b 0a  Extension Thunk.
f3a0: 2a 2a 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  **.** A pointer 
f3b0: 74 6f 20 74 68 65 20 6f 70 61 71 75 65 20 73 71  to the opaque sq
f3c0: 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
f3d0: 65 73 20 73 74 72 75 63 74 75 72 65 20 69 73 20  es structure is 
f3e0: 70 61 73 73 65 64 20 61 73 0a 2a 2a 20 74 68 65  passed as.** the
f3f0: 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
f400: 20 74 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 73   to entry points
f410: 20 6f 66 20 5b 6c 6f 61 64 61 62 6c 65 20 65 78   of [loadable ex
f420: 74 65 6e 73 69 6f 6e 73 5d 2e 20 20 54 68 69 73  tensions].  This
f430: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 6d 75  .** structure mu
f440: 73 74 20 62 65 20 74 79 70 65 64 65 66 65 64 20  st be typedefed 
f450: 69 6e 20 6f 72 64 65 72 20 74 6f 20 77 6f 72 6b  in order to work
f460: 20 61 72 6f 75 6e 64 20 63 6f 6d 70 69 6c 65 72   around compiler
f470: 20 77 61 72 6e 69 6e 67 73 0a 2a 2a 20 6f 6e 20   warnings.** on 
f480: 73 6f 6d 65 20 70 6c 61 74 66 6f 72 6d 73 2e 0a  some platforms..
f490: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
f4a0: 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72 6f  t sqlite3_api_ro
f4b0: 75 74 69 6e 65 73 20 73 71 6c 69 74 65 33 5f 61  utines sqlite3_a
f4c0: 70 69 5f 72 6f 75 74 69 6e 65 73 3b 0a 0a 2f 2a  pi_routines;../*
f4d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
f4e0: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
f4f0: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
f500: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
f510: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
f520: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
f530: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
f540: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
f550: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
f560: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
f570: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
f580: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
f590: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
f5a0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
f5b0: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
f5c0: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
f5d0: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
f5e0: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
f5f0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
f600: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
f610: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
f620: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
f630: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
f640: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
f650: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
f660: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
f670: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
f680: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
f690: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
f6a0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
f6b0: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
f6c0: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
f6d0: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
f6e0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
f6f0: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
f700: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
f710: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
f720: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
f730: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
f740: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
f750: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
f760: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
f770: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
f780: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
f790: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
f7a0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
f7b0: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
f7c0: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
f7d0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
f7e0: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
f7f0: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
f800: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
f810: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
f820: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
f830: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
f840: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
f850: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
f860: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
f870: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
f880: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
f890: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
f8a0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
f8b0: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
f8c0: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
f8d0: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
f8e0: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
f8f0: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
f900: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
f910: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
f920: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
f930: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
f940: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
f950: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
f960: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
f970: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
f980: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
f990: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
f9a0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
f9b0: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
f9c0: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
f9d0: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
f9e0: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
f9f0: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
fa00: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
fa10: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
fa20: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
fa30: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
fa40: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
fa50: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
fa60: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
fa70: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
fa80: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
fa90: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
faa0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
fab0: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
fac0: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
fad0: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
fae0: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
faf0: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
fb00: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
fb10: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
fb20: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
fb30: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
fb40: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
fb50: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
fb60: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
fb70: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
fb80: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
fb90: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
fba0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
fbb0: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
fbc0: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
fbd0: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
fbe0: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
fbf0: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
fc00: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
fc10: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
fc20: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
fc30: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
fc40: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
fc50: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
fc60: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
fc70: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
fc80: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
fc90: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
fca0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
fcb0: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
fcc0: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
fcd0: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
fce0: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
fcf0: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
fd00: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
fd10: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
fd20: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
fd30: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
fd40: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
fd50: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
fd60: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
fd70: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
fd80: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
fd90: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
fda0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
fdb0: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
fdc0: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
fdd0: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
fde0: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
fdf0: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
fe00: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
fe10: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
fe20: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
fe30: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
fe40: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
fe50: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
fe60: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
fe70: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
fe80: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
fe90: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
fea0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
feb0: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
fec0: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
fed0: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
fee0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
fef0: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
ff00: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
ff10: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
ff20: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
ff30: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
ff40: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
ff50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
ff60: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
ff70: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
ff80: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
ff90: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
ffa0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
ffb0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
ffc0: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
ffd0: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
ffe0: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
fff0: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
10000 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
10010 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
10020 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
10030 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
10040 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
10050 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
10060 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
10070 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
10080 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
10090 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
100a0 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
100b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
100c0 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
100d0 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
100e0 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
100f0 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
10100 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
10110 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
10120 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
10130 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
10140 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
10150 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
10160 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
10170 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
10180 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
10190 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
101a0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
101b0 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
101c0 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
101d0 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
101e0 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
101f0 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
10200 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
10210 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
10220 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
10230 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
10240 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
10250 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
10260 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
10270 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
10280 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
10290 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
102a0 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
102b0 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
102c0 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
102d0 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
102e0 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
102f0 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
10300 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
10310 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
10320 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
10330 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
10340 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
10350 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
10360 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
10370 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
10380 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
10390 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
103a0 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
103b0 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
103c0 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
103d0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
103e0 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
103f0 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
10400 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
10410 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
10420 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
10430 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
10440 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
10450 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
10460 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
10470 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
10480 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
10490 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
104a0 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
104b0 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
104c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
104d0 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
104e0 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
104f0 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
10500 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
10510 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
10520 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
10530 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
10540 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
10550 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
10560 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
10570 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
10580 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
10590 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
105a0 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
105b0 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
105c0 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
105d0 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
105e0 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
105f0 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
10600 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
10610 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
10620 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
10630 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
10640 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
10650 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
10660 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
10670 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
10680 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
10690 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
106a0 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
106b0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
106c0 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
106d0 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
106e0 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
106f0 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
10700 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
10710 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
10720 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
10730 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
10740 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
10750 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
10760 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
10770 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
10780 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
10790 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
107a0 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
107b0 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
107c0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
107d0 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
107e0 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
107f0 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
10800 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
10810 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
10820 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
10830 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
10840 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
10850 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
10860 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
10870 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
10880 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
10890 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
108a0 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
108b0 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
108c0 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
108d0 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
108e0 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
108f0 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
10900 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
10910 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
10920 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
10930 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
10940 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
10950 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
10960 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
10970 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
10980 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
10990 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
109a0 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
109b0 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
109c0 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
109d0 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
109e0 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
109f0 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
10a00 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
10a10 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
10a20 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
10a30 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
10a40 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
10a50 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
10a60 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
10a70 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
10a80 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
10a90 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
10aa0 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
10ab0 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
10ac0 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
10ad0 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
10ae0 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
10af0 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
10b00 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
10b10 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
10b20 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
10b30 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
10b40 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
10b50 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
10b60 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
10b70 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
10b80 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
10b90 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
10ba0 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
10bb0 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
10bc0 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
10bd0 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
10be0 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
10bf0 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
10c00 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
10c10 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
10c20 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
10c30 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
10c40 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
10c50 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
10c60 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
10c70 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
10c80 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
10c90 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
10ca0 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
10cb0 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
10cc0 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
10cd0 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
10ce0 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
10cf0 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
10d00 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
10d10 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
10d20 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
10d30 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
10d40 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
10d50 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
10d60 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
10d70 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
10d80 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
10d90 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
10da0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
10db0 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
10dc0 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
10dd0 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
10de0 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
10df0 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
10e00 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
10e10 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
10e20 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
10e30 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
10e40 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
10e50 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
10e60 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
10e70 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
10e80 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
10e90 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
10ea0 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
10eb0 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
10ec0 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
10ed0 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
10ee0 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
10ef0 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
10f00 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
10f10 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
10f20 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
10f30 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
10f40 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
10f50 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
10f60 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
10f70 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
10f80 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
10f90 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
10fa0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
10fb0 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
10fc0 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
10fd0 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
10fe0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
10ff0 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
11000 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
11010 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
11020 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
11030 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
11040 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
11050 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
11060 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
11070 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
11080 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
11090 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
110a0 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
110b0 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
110c0 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
110d0 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
110e0 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
110f0 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
11100 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
11110 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
11120 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
11130 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
11140 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
11150 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
11160 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
11170 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
11180 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
11190 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
111a0 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
111b0 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
111c0 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
111d0 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
111e0 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
111f0 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
11200 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
11210 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
11220 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
11230 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
11240 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
11250 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
11260 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
11270 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
11280 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
11290 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
112a0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
112b0 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
112c0 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
112d0 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
112e0 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
112f0 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
11300 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
11310 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
11320 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
11330 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
11340 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
11350 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
11360 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
11370 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
11380 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
11390 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
113a0 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
113b0 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
113c0 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
113d0 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
113e0 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
113f0 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
11400 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
11410 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
11420 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
11430 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
11440 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
11450 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
11460 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
11470 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
11480 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
11490 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
114a0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
114b0 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
114c0 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
114d0 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
114e0 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
114f0 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
11500 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
11510 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
11520 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
11530 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
11540 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
11550 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
11560 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
11570 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
11580 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
11590 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
115a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
115b0 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
115c0 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
115d0 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
115e0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
115f0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
11600 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
11610 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
11620 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
11630 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
11640 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
11650 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
11660 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
11670 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
11680 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
11690 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
116a0 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
116b0 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
116c0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
116d0 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
116e0 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
116f0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
11700 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
11710 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
11720 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
11730 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
11740 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
11750 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
11760 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
11770 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
11780 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
11790 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
117a0 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
117b0 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
117c0 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
117d0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
117e0 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
117f0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
11800 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
11810 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
11820 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
11830 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
11840 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
11850 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
11860 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
11870 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
11880 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
11890 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
118a0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
118b0 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
118c0 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
118d0 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
118e0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
118f0 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
11900 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
11910 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
11920 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
11930 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
11940 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
11950 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
11960 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
11970 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
11980 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
11990 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
119a0 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
119b0 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
119c0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
119d0 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
119e0 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
119f0 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
11a00 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
11a10 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
11a20 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
11a30 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
11a40 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
11a50 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
11a60 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
11a70 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
11a80 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
11a90 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
11aa0 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
11ab0 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
11ac0 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
11ad0 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
11ae0 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
11af0 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
11b00 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
11b10 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
11b20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
11b30 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
11b40 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
11b50 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
11b60 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
11b70 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
11b80 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
11b90 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
11ba0 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
11bb0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
11bc0 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
11bd0 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
11be0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
11bf0 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
11c00 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
11c10 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
11c20 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
11c30 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
11c40 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
11c50 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
11c60 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
11c70 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
11c80 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
11c90 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
11ca0 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
11cb0 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
11cc0 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
11cd0 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
11ce0 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
11cf0 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
11d00 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
11d10 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
11d20 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
11d30 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
11d40 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
11d50 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
11d60 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
11d70 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
11d80 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
11d90 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
11da0 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
11db0 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
11dc0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
11dd0 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
11de0 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
11df0 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
11e00 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
11e10 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
11e20 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
11e30 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
11e40 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
11e50 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
11e60 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
11e70 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
11e80 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
11e90 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
11ea0 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
11eb0 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
11ec0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
11ed0 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
11ee0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
11ef0 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
11f00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
11f10 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
11f20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
11f30 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
11f40 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
11f50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
11f60 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
11f70 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
11f80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11f90 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
11fa0 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
11fb0 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
11fc0 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
11fd0 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
11fe0 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
11ff0 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
12000 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
12010 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
12020 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
12030 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
12040 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
12050 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
12060 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
12070 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
12080 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
12090 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
120a0 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
120b0 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
120c0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
120d0 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
120e0 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
120f0 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
12100 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
12110 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
12120 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
12130 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
12140 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
12150 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
12160 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
12170 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
12180 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
12190 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
121a0 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
121b0 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65 73 70  n on the corresp
121c0 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
121d0 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
121e0 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
121f0 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
12200 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
12210 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
12220 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
12230 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
12240 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
12250 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
12260 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
12270 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
12280 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
12290 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
122a0 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
122b0 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
122c0 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
122d0 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
122e0 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
122f0 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
12300 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
12310 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
12320 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
12330 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
12340 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
12350 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
12360 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
12370 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
12380 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
12390 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
123a0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
123b0 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
123c0 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
123d0 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
123e0 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
123f0 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
12400 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
12410 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
12420 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
12430 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
12440 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
12450 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
12460 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12470 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
12480 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
12490 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
124a0 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
124b0 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
124c0 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
124d0 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
124e0 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
124f0 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
12500 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
12510 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
12520 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
12530 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
12540 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
12550 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
12560 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
12570 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
12580 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
12590 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
125a0 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
125b0 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
125c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
125d0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
125e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
125f0 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
12600 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
12610 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
12620 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
12630 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
12640 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
12650 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
12660 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
12670 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
12680 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
12690 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
126a0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
126b0 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
126c0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
126d0 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
126e0 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
126f0 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
12700 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
12710 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
12720 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
12730 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
12740 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
12750 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
12760 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
12770 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
12780 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
12790 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
127a0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
127b0 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
127c0 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
127d0 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
127e0 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
127f0 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
12800 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
12810 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
12820 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
12830 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
12840 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
12850 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
12860 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
12870 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
12880 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12890 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
128a0 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
128b0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
128c0 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
128d0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
128e0 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
128f0 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
12900 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
12910 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
12920 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
12930 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
12940 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
12950 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
12960 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
12970 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
12980 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
12990 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
129a0 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
129b0 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
129c0 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
129d0 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
129e0 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
129f0 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
12a00 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
12a10 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
12a20 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
12a30 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
12a40 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
12a50 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
12a60 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
12a70 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
12a80 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
12a90 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
12aa0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
12ab0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
12ac0 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
12ad0 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
12ae0 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
12af0 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
12b00 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
12b10 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
12b20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
12b30 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
12b40 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
12b50 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
12b60 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12b70 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
12b80 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
12b90 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
12ba0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
12bb0 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
12bc0 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
12bd0 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
12be0 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
12bf0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12c00 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
12c10 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
12c20 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
12c30 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
12c40 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
12c50 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
12c60 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
12c70 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
12c80 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
12c90 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
12ca0 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
12cb0 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
12cc0 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
12cd0 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
12ce0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12cf0 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
12d00 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
12d10 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
12d20 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
12d30 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
12d40 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
12d50 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
12d60 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
12d70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
12d80 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
12d90 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
12da0 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
12db0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
12dc0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
12dd0 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
12de0 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
12df0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
12e00 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
12e10 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
12e20 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
12e30 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
12e40 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
12e50 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
12e60 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
12e70 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
12e80 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
12e90 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
12ea0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
12eb0 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
12ec0 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
12ed0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12ee0 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
12ef0 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
12f00 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
12f10 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
12f20 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
12f30 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
12f40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
12f50 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
12f60 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
12f70 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
12f80 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
12f90 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
12fa0 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
12fb0 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
12fc0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
12fd0 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
12fe0 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
12ff0 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
13000 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
13010 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
13020 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
13030 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
13040 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
13050 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
13060 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
13070 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
13080 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
13090 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
130a0 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
130b0 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
130c0 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
130d0 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
130e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
130f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
13100 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
13110 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
13120 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
13130 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
13140 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
13150 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
13160 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
13170 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
13180 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
13190 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
131a0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
131b0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
131c0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
131d0 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
131e0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
131f0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
13200 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
13210 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
13220 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
13230 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
13240 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
13250 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
13260 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
13270 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
13280 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
13290 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
132a0 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
132b0 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
132c0 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
132d0 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
132e0 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
132f0 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
13300 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
13310 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
13320 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
13330 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
13340 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
13350 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
13360 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13370 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
13380 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
13390 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
133a0 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
133b0 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
133c0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
133d0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
133e0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
133f0 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
13400 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
13410 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
13420 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
13430 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
13440 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ilure..*/.SQLITE
13450 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
13460 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
13470 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
13480 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
13490 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  wn(void);.SQLITE
134a0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
134b0 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
134c0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
134d0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
134e0 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
134f0 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
13500 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
13510 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rary.**.** The s
13520 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
13530 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
13540 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
13550 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
13560 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
13570 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
13580 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
13590 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
135a0 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
135b0 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
135c0 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
135d0 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
135e0 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
135f0 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
13600 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
13610 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
13620 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
13630 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
13640 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
13650 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
13660 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
13670 0a 2a 2a 20 3c 62 3e 54 68 65 20 73 71 6c 69 74  .** <b>The sqlit
13680 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
13690 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
136a0 65 61 64 73 61 66 65 2e 20 54 68 65 20 61 70 70  eadsafe. The app
136b0 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
136c0 20 65 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   ensure that no 
136d0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
136e0 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
136f0 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
13700 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
13710 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
13720 73 20 72 75 6e 6e 69 6e 67 2e 3c 2f 62 3e 0a 2a  s running.</b>.*
13730 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
13740 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
13750 61 63 65 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ace.** may only 
13760 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72  be invoked prior
13770 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74   to library init
13780 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67  ialization using
13790 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  .** [sqlite3_ini
137a0 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  tialize()] or af
137b0 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20  ter shutdown by 
137c0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
137d0 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  n()]..** ^If sql
137e0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
137f0 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
13800 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
13810 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a  e()] and before.
13820 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
13830 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20  down()] then it 
13840 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
13850 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f  TE_MISUSE..** No
13860 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
13870 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t ^sqlite3_confi
13880 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  g() can be calle
13890 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
138a0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
138b0 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61  on of an applica
138c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71  tion-defined [sq
138d0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d  lite3_os_init()]
138e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
138f0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  t argument to sq
13900 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
13910 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
13920 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
13930 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
13940 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
13950 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
13960 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
13970 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
13980 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
13990 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
139a0 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61  n the [configura
139b0 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20  tion option].** 
139c0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
139d0 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  ument..**.** ^Wh
139e0 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
139f0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
13a00 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
13a10 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  () returns [SQLI
13a20 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74  TE_OK]..** ^If t
13a30 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b  he option is unk
13a40 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69  nown or SQLite i
13a50 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20  s unable to set 
13a60 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68  the option.** th
13a70 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
13a80 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
13a90 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ro [error code].
13aa0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
13ab0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
13ac0 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
13ad0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
13ae0 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
13af0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
13b00 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
13b10 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
13b20 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e  3_db_config() in
13b30 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
13b40 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72  to make configur
13b50 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
13b60 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20   to a [database 
13b70 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68  connection].  Th
13b80 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73  e interface is s
13b90 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71  imilar to.** [sq
13ba0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13bb0 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20  except that the 
13bc0 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f  changes apply to
13bd0 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61   a single.** [da
13be0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13bf0 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e  n] (specified in
13c00 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13c10 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent)..**.** The 
13c20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
13c30 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
13c40 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69  nfig(D,V,...)  i
13c50 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
13c60 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
13c70 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74  IDE | configurat
13c80 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69  ion verb] - an i
13c90 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20  nteger code .** 
13ca0 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77  that indicates w
13cb0 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68  hat aspect of th
13cc0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
13cd0 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67  ection] is being
13ce0 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20   configured..** 
13cf0 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
13d00 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64  ents vary depend
13d10 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69  ing on the confi
13d20 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a  guration verb..*
13d30 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73  *.** ^Calls to s
13d40 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
13d50 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45  () return SQLITE
13d60 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  _OK if and only 
13d70 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69  if.** the call i
13d80 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63  s considered suc
13d90 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49  cessful..*/.SQLI
13da0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
13db0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c  e3_db_config(sql
13dc0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e  ite3*, int op, .
13dd0 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ..);../*.** CAPI
13de0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
13df0 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73  ocation Routines
13e00 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e  .**.** An instan
13e10 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
13e20 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e  t defines the in
13e30 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20  terface between 
13e40 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f  SQLite.** and lo
13e50 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
13e60 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
13e70 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f  es..**.** This o
13e80 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e  bject is used in
13e90 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20   only one place 
13ea0 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e  in the SQLite in
13eb0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f  terface..** A po
13ec0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
13ed0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
13ee0 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d  ect is the argum
13ef0 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ent to.** [sqlit
13f00 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65  e3_config()] whe
13f10 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  n the configurat
13f20 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ion option is.**
13f30 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13f40 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49  MALLOC] or [SQLI
13f50 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
13f60 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72  LOC].  .** By cr
13f70 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e  eating an instan
13f80 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
13f90 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67  t.** and passing
13fa0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
13fb0 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
13fc0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a  CONFIG_MALLOC]).
13fd0 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67  ** during config
13fe0 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c  uration, an appl
13ff0 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63  ication can spec
14000 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
14010 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
14020 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
14030 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20  m for SQLite to 
14040 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  use for all of i
14050 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65  ts.** dynamic me
14060 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  mory needs..**.*
14070 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69  * Note that SQLi
14080 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65  te comes with se
14090 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20  veral [built-in 
140a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
140b0 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70  s].** that are p
140c0 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74  erfectly adequat
140d0 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68  e for the overwh
140e0 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20  elming majority 
140f0 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  of applications.
14100 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73  ** and that this
14110 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20   object is only 
14120 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79  useful to a tiny
14130 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70   minority of app
14140 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74  lications.** wit
14150 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65  h specialized me
14160 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14170 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54  requirements.  T
14180 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  his object is.**
14190 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e   also used durin
141a0 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c  g testing of SQL
141b0 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
141c0 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
141d0 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
141e0 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
141f0 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79  simulates memory
14200 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63   out-of-memory c
14210 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20  onditions in.** 
14220 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20  order to verify 
14230 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f  that SQLite reco
14240 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20  vers gracefully 
14250 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e  from such.** con
14260 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54  ditions..**.** T
14270 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61  he xMalloc, xRea
14280 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20  lloc, and xFree 
14290 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
142a0 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
142b0 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
142c0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e  ) and free() fun
142d0 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20  ctions from the 
142e0 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
142f0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  ry..** ^SQLite g
14300 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
14310 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14320 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f  nt to.** xReallo
14330 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61  c is always a va
14340 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
14350 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20  a prior call to 
14360 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20  xRoundup..**.** 
14370 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
14380 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
14390 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
143a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
143b0 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
143c0 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
143d0 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
143e0 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
143f0 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
14400 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
14410 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
14420 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
14430 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
14440 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
14450 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
14460 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
14470 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
14480 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
14490 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
144a0 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
144b0 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
144c0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
144d0 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
144e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
144f0 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
14500 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
14510 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
14520 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
14530 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
14540 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
14550 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
14560 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
14570 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
14580 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
14590 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
145a0 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
145b0 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
145c0 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
145d0 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
145e0 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
145f0 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
14600 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
14610 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
14620 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
14630 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
14640 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
14650 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
14660 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a   For example,.**
14670 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
14680 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
14690 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
146a0 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
146b0 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
146c0 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
146d0 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
146e0 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
146f0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
14700 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
14710 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
14720 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
14730 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
14740 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
14750 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
14760 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
14770 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
14780 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
14790 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
147a0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
147b0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
147c0 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
147d0 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
147e0 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
147f0 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
14800 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
14810 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
14820 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
14830 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
14840 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
14850 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
14860 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
14870 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
14880 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
14890 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
148a0 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
148b0 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
148c0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
148d0 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
148e0 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
148f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14900 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
14910 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
14920 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
14930 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
14940 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
14950 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
14960 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
14970 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
14980 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
14990 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
149a0 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
149b0 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
149c0 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
149d0 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
149e0 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
149f0 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
14a00 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
14a10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
14a20 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
14a30 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
14a40 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
14a50 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
14a60 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
14a70 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
14a80 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
14a90 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
14aa0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14ab0 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
14ac0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
14ad0 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
14ae0 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
14af0 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
14b00 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
14b10 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
14b20 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
14b30 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
14b40 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
14b50 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
14b60 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
14b70 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
14b80 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
14b90 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
14ba0 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
14bb0 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
14bc0 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
14bd0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
14be0 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
14bf0 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
14c00 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
14c10 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
14c20 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
14c30 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
14c40 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
14c50 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
14c60 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
14c70 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
14c80 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
14c90 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
14ca0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
14cb0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
14cc0 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
14cd0 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
14ce0 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
14cf0 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
14d00 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
14d10 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
14d20 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
14d30 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
14d40 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
14d50 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
14d60 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
14d70 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
14d80 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14d90 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
14da0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
14db0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14dc0 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
14dd0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
14de0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
14df0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14e00 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
14e10 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
14e20 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
14e30 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
14e40 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14e50 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
14e60 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
14e70 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
14e80 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
14e90 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
14ea0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14eb0 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
14ec0 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
14ed0 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
14ee0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
14ef0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
14f00 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
14f10 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
14f20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
14f30 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
14f40 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14f50 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
14f60 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
14f70 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14f80 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
14f90 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14fa0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
14fb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
14fc0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
14fd0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
14fe0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
14ff0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
15000 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
15010 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
15020 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
15030 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
15040 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
15050 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
15060 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
15070 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
15080 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
15090 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
150a0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
150b0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
150c0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
150d0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
150e0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
150f0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
15100 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
15110 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
15120 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
15130 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
15140 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
15150 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
15160 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
15170 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
15180 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
15190 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
151a0 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
151b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
151c0 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
151d0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
151e0 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
151f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15200 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
15210 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15220 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
15230 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
15240 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
15250 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
15260 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
15270 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
15280 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
15290 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
152a0 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
152b0 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
152c0 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
152d0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
152e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
152f0 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
15300 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
15310 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
15320 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
15330 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
15340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15350 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
15360 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
15370 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
15380 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
15390 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
153a0 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
153b0 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
153c0 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
153d0 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
153e0 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
153f0 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
15400 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
15410 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15420 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
15430 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
15440 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
15450 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
15460 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
15470 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
15480 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
15490 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
154a0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
154b0 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
154c0 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
154d0 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
154e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
154f0 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
15500 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
15510 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
15520 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
15530 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
15540 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15550 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
15560 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
15570 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
15580 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
15590 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
155a0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
155b0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
155c0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
155d0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
155e0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
155f0 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
15600 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
15610 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
15620 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
15630 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
15640 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
15650 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
15660 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15670 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
15680 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
15690 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
156a0 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
156b0 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
156c0 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
156d0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
156e0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
156f0 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
15700 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
15710 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
15720 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
15730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
15740 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
15750 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
15760 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
15770 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
15780 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
15790 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
157a0 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
157b0 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
157c0 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
157d0 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
157e0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
157f0 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
15800 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
15810 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
15820 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
15830 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
15840 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15850 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
15860 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
15870 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
15880 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
15890 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
158a0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
158b0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
158c0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
158d0 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
158e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
158f0 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
15900 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
15910 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15920 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
15930 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15940 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
15950 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
15960 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
15970 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOC option takes
15980 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
15990 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a 20  nt which is .** 
159a0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
159b0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
159c0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
159d0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
159e0 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
159f0 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c   specifies.** al
15a00 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
15a10 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
15a20 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74  ation routines t
15a30 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
15a40 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d  ce of.** the mem
15a50 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
15a60 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e  outines built in
15a70 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51  to SQLite.)^ ^SQ
15a80 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74  Lite makes.** it
15a90 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
15aa0 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e  py of the conten
15ab0 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  t of the [sqlite
15ac0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
15ad0 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f  tructure.** befo
15ae0 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  re the [sqlite3_
15af0 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72  config()] call r
15b00 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  eturns.</dd>.**.
15b10 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15b20 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c  IG_GETMALLOC]] <
15b30 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15b40 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  _GETMALLOC</dt>.
15b50 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51  ** <dd> ^(The SQ
15b60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15b70 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
15b80 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15b90 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
15ba0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
15bb0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
15bc0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
15bd0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
15be0 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
15bf0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
15c00 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
15c10 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
15c20 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
15c30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15c40 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
15c50 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
15c60 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
15c70 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
15c80 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
15c90 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
15ca0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
15cb0 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
15cc0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
15cd0 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
15ce0 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
15cf0 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
15d00 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
15d10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
15d20 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
15d30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
15d40 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
15d50 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
15d60 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
15d70 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e  option takes sin
15d80 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  gle argument of 
15d90 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74  type int,.** int
15da0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f  erpreted as a bo
15db0 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61  olean, which ena
15dc0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
15dd0 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20   the collection 
15de0 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  of.** memory all
15df0 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
15e00 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
15e10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
15e20 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a 20 64  tistics are.** d
15e30 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c  isabled, the fol
15e40 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e  lowing SQLite in
15e50 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20  terfaces become 
15e60 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a  non-operational:
15e70 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20  .**   <ul>.**   
15e80 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
15e90 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20  mory_used()].** 
15ea0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
15eb0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
15ec0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
15ed0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
15ee0 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20  _limit64()].**  
15ef0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73   <li> [sqlite3_s
15f00 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20 20 20  tatus64()].**   
15f10 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f  </ul>)^.** ^Memo
15f20 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ry allocation st
15f30 61 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61  atistics are ena
15f40 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
15f50 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73  unless SQLite is
15f60 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  .** compiled wit
15f70 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  h [SQLITE_DEFAUL
15f80 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69  T_MEMSTATUS]=0 i
15f90 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d  n which case mem
15fa0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ory.** allocatio
15fb0 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
15fc0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
15fd0 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  ault..** </dd>.*
15fe0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
15ff0 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c  NFIG_SCRATCH]] <
16000 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16010 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a  _SCRATCH</dt>.**
16020 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
16030 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
16040 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
16050 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
16060 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74  y buffer.** that
16070 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
16080 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  for scratch memo
16090 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61 72 65  ry.  ^(There are
160a0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
160b0 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  .** to SQLITE_CO
160c0 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20 20 41  NFIG_SCRATCH:  A
160d0 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
160e0 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
160f0 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
16100 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
16110 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
16120 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
16130 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
16140 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
16150 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
16160 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
16170 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
16180 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
16190 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  )^.** The first 
161a0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
161b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
161c0 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
161d0 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
161e0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
161f0 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
16200 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f 74 20  SQLite will not 
16210 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  use more than on
16220 65 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  e scratch buffer
16230 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a 2a 2a  s per thread..**
16240 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65   ^SQLite will ne
16250 76 65 72 20 72 65 71 75 65 73 74 20 61 20 73 63  ver request a sc
16260 72 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61  ratch buffer tha
16270 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36  t is more than 6
16280 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61  .** times the da
16290 74 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65  tabase page size
162a0 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
162b0 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
162c0 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
162d0 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
162e0 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
162f0 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
16300 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
16310 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
16320 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
16330 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
16340 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
16350 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e  ded.<p>.** ^When
16360 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
16370 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20 61 6d   provides any am
16380 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63 68 20  ount of scratch 
16390 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a 2a 20  memory using.** 
163a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
163b0 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20 61 76  RATCH, SQLite av
163c0 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61 72 79  oids unnecessary
163d0 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c 69 74   large.** [sqlit
163e0 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70 20 61  e3_malloc|heap a
163f0 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20  llocations]..** 
16400 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20 5b 52  This can help [R
16410 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72 65 76  obson proof|prev
16420 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ent memory alloc
16430 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73 5d 20  ation failures] 
16440 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a 20 66  due to heap.** f
16450 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 20  ragmentation in 
16460 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62 65 64  low-memory embed
16470 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 20  ded systems..** 
16480 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16490 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
164a0 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
164b0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
164c0 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
164d0 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
164e0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 6f 70  FIG_PAGECACHE op
164f0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
16500 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 2a 2a 20   memory pool.** 
16510 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
16520 75 73 65 20 66 6f 72 20 74 68 65 20 64 61 74 61  use for the data
16530 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
16540 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
16550 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69   page.** cache i
16560 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
16570 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75  .** This configu
16580 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
16590 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61 6e 20 61   a no-op if an a
165a0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
165b0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
165c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
165d0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
165e0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
165f0 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a 2a 20 5e  G_PCACHE2]..** ^
16600 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
16610 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c  arguments to SQL
16620 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
16630 41 43 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20  ACHE: A pointer 
16640 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69  to.** 8-byte ali
16650 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28 70 4d 65  gned memory (pMe
16660 6d 29 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  m), the size of 
16670 65 61 63 68 20 70 61 67 65 20 63 61 63 68 65 20  each page cache 
16680 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  line (sz),.** an
16690 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
166a0 63 61 63 68 65 20 6c 69 6e 65 73 20 28 4e 29 2e  cache lines (N).
166b0 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
166c0 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
166d0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
166e0 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
166f0 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
16700 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
16710 31 32 20 61 6e 64 20 36 35 35 33 36 29 20 70 6c  12 and 65536) pl
16720 75 73 20 73 6f 6d 65 20 65 78 74 72 61 20 62 79  us some extra by
16730 74 65 73 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20  tes for each.** 
16740 70 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54  page header.  ^T
16750 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78 74  he number of ext
16760 72 61 20 62 79 74 65 73 20 6e 65 65 64 65 64 20  ra bytes needed 
16770 62 79 20 74 68 65 20 70 61 67 65 20 68 65 61 64  by the page head
16780 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20 64 65 74  er.** can be det
16790 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 20 5b 53  ermined using [S
167a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
167b0 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a 2a 20 5e  CHE_HDRSZ]..** ^
167c0 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20  It is harmless, 
167d0 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77  apart from the w
167e0 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  asted memory,.**
167f0 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61 72 61   for the sz para
16800 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61 72 67  meter to be larg
16810 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73 61 72  er than necessar
16820 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a 2a 2a 20  y.  The pMem.** 
16830 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
16840 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
16850 6f 69 6e 74 65 72 20 6f 72 20 61 20 70 6f 69 6e  ointer or a poin
16860 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ter to an 8-byte
16870 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62 6c 6f 63  .** aligned bloc
16880 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f 66 20 61  k of memory of a
16890 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
168a0 65 73 2c 20 6f 74 68 65 72 77 69 73 65 0a 2a 2a  es, otherwise.**
168b0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
168c0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
168d0 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70 4d 65 6d  d..** ^When pMem
168e0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
168f0 4c 69 74 65 20 77 69 6c 6c 20 73 74 72 69 76 65  Lite will strive
16900 20 74 6f 20 75 73 65 20 74 68 65 20 6d 65 6d 6f   to use the memo
16910 72 79 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 74  ry provided.** t
16920 6f 20 73 61 74 69 73 66 79 20 70 61 67 65 20 63  o satisfy page c
16930 61 63 68 65 20 6e 65 65 64 73 2c 20 66 61 6c 6c  ache needs, fall
16940 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b 73 71 6c  ing back to [sql
16950 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
16960 66 0a 2a 2a 20 61 20 70 61 67 65 20 63 61 63 68  f.** a page cach
16970 65 20 6c 69 6e 65 20 69 73 20 6c 61 72 67 65 72  e line is larger
16980 20 74 68 61 6e 20 73 7a 20 62 79 74 65 73 20 6f   than sz bytes o
16990 72 20 69 66 20 61 6c 6c 20 6f 66 20 74 68 65 20  r if all of the 
169a0 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a 2a 20 69  pMem buffer.** i
169b0 73 20 65 78 68 61 75 73 74 65 64 2e 0a 2a 2a 20  s exhausted..** 
169c0 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e 55 4c 4c  ^If pMem is NULL
169d0 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e 2d 7a 65   and N is non-ze
169e0 72 6f 2c 20 74 68 65 6e 20 65 61 63 68 20 64 61  ro, then each da
169f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16a00 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20 69 6e 69  n.** does an ini
16a10 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c 6f 63 61  tial bulk alloca
16a20 74 69 6f 6e 20 66 6f 72 20 70 61 67 65 20 63 61  tion for page ca
16a30 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 66 72  che memory.** fr
16a40 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
16a50 6f 63 28 29 5d 20 73 75 66 66 69 63 69 65 6e 74  oc()] sufficient
16a60 20 66 6f 72 20 4e 20 63 61 63 68 65 20 6c 69 6e   for N cache lin
16a70 65 73 20 69 66 20 4e 20 69 73 20 70 6f 73 69 74  es if N is posit
16a80 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20 2d 31 30  ive or.** of -10
16a90 32 34 2a 4e 20 62 79 74 65 73 20 69 66 20 4e 20  24*N bytes if N 
16aa0 69 73 20 6e 65 67 61 74 69 76 65 2c 20 2e 20 5e  is negative, . ^
16ab0 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
16ac0 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
16ad0 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
16ae0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
16af0 69 64 65 64 20 62 79 20 74 68 65 20 69 6e 69 74  ided by the init
16b00 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f  ial.** allocatio
16b10 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 67  n, then SQLite g
16b20 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
16b30 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70 61 72 61  malloc()] separa
16b40 74 65 6c 79 20 66 6f 72 20 65 61 63 68 0a 2a 2a  tely for each.**
16b50 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 61 63 68   additional cach
16b60 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  e line. </dd>.**
16b70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16b80 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53  FIG_HEAP]] <dt>S
16b90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
16ba0 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  P</dt>.** <dd> ^
16bb0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16bc0 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20 73 70  G_HEAP option sp
16bd0 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
16be0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 0a   memory buffer .
16bf0 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  ** that SQLite w
16c00 69 6c 6c 20 75 73 65 20 66 6f 72 20 61 6c 6c 20  ill use for all 
16c10 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d  of its dynamic m
16c20 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
16c30 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64   needs.** beyond
16c40 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 20   those provided 
16c50 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43  for by [SQLITE_C
16c60 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61  ONFIG_SCRATCH] a
16c70 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  nd.** [SQLITE_CO
16c80 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
16c90 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
16ca0 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69  CONFIG_HEAP opti
16cb0 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  on is only avail
16cc0 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69  able if SQLite i
16cd0 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69  s compiled.** wi
16ce0 74 68 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  th either [SQLIT
16cf0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33  E_ENABLE_MEMSYS3
16d00 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ] or [SQLITE_ENA
16d10 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64  BLE_MEMSYS5] and
16d20 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
16d30 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e  ITE_ERROR] if in
16d40 76 6f 6b 65 64 20 6f 74 68 65 72 77 69 73 65 2e  voked otherwise.
16d50 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74  .** ^There are t
16d60 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74  hree arguments t
16d70 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  o SQLITE_CONFIG_
16d80 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79  HEAP:.** An 8-by
16d90 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74  te aligned point
16da0 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  er to the memory
16db0 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  ,.** the number 
16dc0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
16dd0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61  memory buffer, a
16de0 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61  nd the minimum a
16df0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a  llocation size..
16e00 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74  ** ^If the first
16e10 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
16e20 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73  mory pointer) is
16e30 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69   NULL, then SQLi
16e40 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f  te reverts.** to
16e50 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75   using its defau
16e60 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
16e70 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20  tor (the system 
16e80 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65  malloc() impleme
16e90 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64  ntation),.** und
16ea0 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69  oing any prior i
16eb0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51  nvocation of [SQ
16ec0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
16ed0 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a  OC].  ^If the.**
16ee0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20   memory pointer 
16ef0 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e  is not NULL then
16f00 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65   the alternative
16f10 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
16f20 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20  ator is engaged 
16f30 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66  to handle all of
16f40 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20   SQLites memory 
16f50 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
16f60 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  ..** The first p
16f70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
16f80 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74  ry pointer) must
16f90 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
16fa0 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e  n 8-byte.** boun
16fb0 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65  dary or subseque
16fc0 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  nt behavior of S
16fd0 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e  QLite will be un
16fe0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20  defined..** The 
16ff0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
17000 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65  on size is cappe
17010 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73  d at 2**12. Reas
17020 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a  onable values.**
17030 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d   for the minimum
17040 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
17050 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67   are 2**5 throug
17060 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a  h 2**8.</dd>.**.
17070 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17080 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  IG_MUTEX]] <dt>S
17090 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
170a0 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EX</dt>.** <dd> 
170b0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
170c0 46 49 47 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e  FIG_MUTEX option
170d0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
170e0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
170f0 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
17100 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
17110 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
17120 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
17130 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61  ucture..** The a
17140 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
17150 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  s alternative lo
17160 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
17170 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
17180 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65 20 74 68  d.** in place th
17190 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
171a0 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
171b0 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
171c0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  akes a copy of.*
171d0 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
171e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
171f0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
17200 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
17210 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
17220 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
17230 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
17240 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
17250 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
17260 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
17270 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
17280 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
17290 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
172a0 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
172b0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
172c0 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
172d0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
172e0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
172f0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
17300 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
17310 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
17320 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
17330 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
17340 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
17350 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
17360 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
17370 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
17380 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
17390 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
173a0 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43  > ^(The SQLITE_C
173b0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 6f  ONFIG_GETMUTEX o
173c0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
173d0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
173e0 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e  ich.** is a poin
173f0 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
17400 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
17410 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
17420 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
17430 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
17440 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
17450 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
17460 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
17470 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
17480 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
17490 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
174a0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
174b0 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
174c0 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
174d0 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
174e0 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
174f0 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
17500 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
17510 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
17520 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
17530 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
17540 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
17550 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
17560 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
17570 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
17580 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
17590 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
175a0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
175b0 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
175c0 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
175d0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
175e0 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
175f0 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
17600 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
17610 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
17620 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
17630 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17640 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
17650 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
17660 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
17670 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
17680 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
17690 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
176a0 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
176b0 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
176c0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70  FIG_LOOKASIDE op
176d0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
176e0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
176f0 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64  termine.** the d
17700 65 66 61 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c  efault size of l
17710 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
17720 6f 6e 20 65 61 63 68 20 5b 64 61 74 61 62 61 73  on each [databas
17730 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
17740 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
17750 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
17760 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
17770 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
17780 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
17790 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
177a0 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
177b0 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
177c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
177d0 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f  .)^  ^(SQLITE_CO
177e0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a  NFIG_LOOKASIDE.*
177f0 2a 20 73 65 74 73 20 74 68 65 20 3c 69 3e 64 65  * sets the <i>de
17800 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73  fault</i> lookas
17810 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53  ide size. The [S
17820 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
17830 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74  OOKASIDE].** opt
17840 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ion to [sqlite3_
17850 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e  db_config()] can
17860 20 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e   be used to chan
17870 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
17880 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
17890 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
178a0 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c  connections.)^ <
178b0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
178c0 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
178d0 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  E2]] <dt>SQLITE_
178e0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f  CONFIG_PCACHE2</
178f0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
17900 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17910 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74  PCACHE2 option t
17920 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
17930 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
17940 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
17950 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
17960 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
17970 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65  ject.  This obje
17980 63 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ct specifies.** 
17990 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f  the interface to
179a0 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63   a custom page c
179b0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
179c0 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74  ion.)^.** ^SQLit
179d0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
179e0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  f the [sqlite3_p
179f0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
17a00 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a  object.</dd>.**.
17a10 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17a20 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20  IG_GETPCACHE2]] 
17a30 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17a40 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74  G_GETPCACHE2</dt
17a50 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
17a60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
17a70 54 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 20  TPCACHE2 option 
17a80 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
17a90 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
17aa0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17ab0 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61   an [sqlite3_pca
17ac0 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62  che_methods2] ob
17ad0 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f  ject.  SQLite co
17ae0 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63  pies of.** the c
17af0 75 72 72 65 6e 74 20 70 61 67 65 20 63 61 63 68  urrent page cach
17b00 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
17b10 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63   into that objec
17b20 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  t.)^ </dd>.**.**
17b30 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
17b40 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _LOG]] <dt>SQLIT
17b50 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74  E_CONFIG_LOG</dt
17b60 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51  >.** <dd> The SQ
17b70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
17b80 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17b90 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20  o configure the 
17ba0 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c  SQLite.** global
17bb0 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a   [error log]..**
17bc0 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f   (^The SQLITE_CO
17bd0 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
17be0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
17bf0 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74  nts: a pointer t
17c00 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  o a.** function 
17c10 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e  with a call sign
17c20 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29  ature of void(*)
17c30 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
17c40 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64   char*), .** and
17c50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f   a pointer to vo
17c60 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63  id. ^If the func
17c70 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
17c80 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a  not NULL, it is.
17c90 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73  ** invoked by [s
17ca0 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f  qlite3_log()] to
17cb0 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f   process each lo
17cc0 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  gging event.  ^I
17cd0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
17ce0 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c  n pointer is NUL
17cf0 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  L, the [sqlite3_
17d00 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  log()] interface
17d10 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70   becomes a no-op
17d20 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70  ..** ^The void p
17d30 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 74  ointer that is t
17d40 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
17d50 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e  nt to SQLITE_CON
17d60 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61  FIG_LOG is.** pa
17d70 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20  ssed through as 
17d80 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
17d90 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69  ter to the appli
17da0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c  cation-defined l
17db0 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  ogger.** functio
17dc0 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74 20  n whenever that 
17dd0 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f  function is invo
17de0 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  ked.  ^The secon
17df0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  d parameter to.*
17e00 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  * the logger fun
17e10 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20  ction is a copy 
17e20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  of the first par
17e30 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ameter to the co
17e40 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b  rresponding.** [
17e50 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63  sqlite3_log()] c
17e60 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e  all and is inten
17e70 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73  ded to be a [res
17e80 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a  ult code] or an.
17e90 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
17ea0 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65  ult code].  ^The
17eb0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
17ec0 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c   passed to the l
17ed0 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20  ogger is.** log 
17ee0 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66 6f  message after fo
17ef0 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71  rmatting via [sq
17f00 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
17f10 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  ]..** The SQLite
17f20 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61   logging interfa
17f30 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72  ce is not reentr
17f40 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20  ant; the logger 
17f50 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70  function.** supp
17f60 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  lied by the appl
17f70 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
17f80 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69   invoke any SQLi
17f90 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  te interface..**
17fa0 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   In a multi-thre
17fb0 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e  aded application
17fc0 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
17fd0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
17fe0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
17ff0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
18000 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
18010 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
18020 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
18030 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e  NFIG_URI.** <dd>
18040 5e 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  ^(The SQLITE_CON
18050 46 49 47 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74  FIG_URI option t
18060 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
18070 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
18080 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65  nt..** If non-ze
18090 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
180a0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
180b0 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
180c0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
180d0 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49  ero,.** then URI
180e0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
180f0 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 29  bally disabled.)
18100 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c 69  ^ ^If URI handli
18110 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
18120 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66  * enabled, all f
18130 69 6c 65 6e 61 6d 65 73 20 70 61 73 73 65 64 20  ilenames passed 
18140 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
18150 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
18160 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  en_v2()],.** [sq
18170 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20  lite3_open16()] 
18180 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  or.** specified 
18190 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41  as part of [ATTA
181a0 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65  CH] commands are
181b0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
181c0 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73  URIs, regardless
181d0 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f  .** of whether o
181e0 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54  r not the [SQLIT
181f0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
18200 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
18210 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
18220 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
18230 64 2e 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f  d. ^If it is glo
18240 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
18250 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
18260 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
18270 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
18280 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
18290 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
182a0 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
182b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
182c0 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66  opened. ^(By def
182d0 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
182e0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
182f0 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
18300 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
18310 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
18320 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
18330 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
18340 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
18350 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  fined.)^.**.** [
18360 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43  [SQLITE_CONFIG_C
18370 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
18380 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AN]] <dt>SQLITE_
18390 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
183a0 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64  INDEX_SCAN.** <d
183b0 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d>^The SQLITE_CO
183c0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
183d0 44 45 58 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20  DEX_SCAN option 
183e0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69  takes a single i
183f0 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65  nteger.** argume
18400 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
18410 72 70 72 65 74 65 64 20 61 73 20 61 20 62 6f 6f  rpreted as a boo
18420 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f  lean in order to
18430 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
18440 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66  le.** the use of
18450 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
18460 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65  s for full table
18470 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75   scans in the qu
18480 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a  ery optimizer..*
18490 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
184a0 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d  etting is determ
184b0 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  ined.** by the [
184c0 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56  SQLITE_ALLOW_COV
184d0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
184e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
184f0 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e  ption, or is "on
18500 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d  ".** if that com
18510 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
18520 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20   is omitted..** 
18530 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64  The ability to d
18540 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
18550 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
18560 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
18570 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65  e scans.** is be
18580 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72  cause some incor
18590 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67  rectly coded leg
185a0 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  acy applications
185b0 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69   might malfuncti
185c0 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f  on.** when the o
185d0 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65  ptimization is e
185e0 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69  nabled.  Providi
185f0 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74  ng the ability t
18600 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65  o.** disable the
18610 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c   optimization al
18620 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20  lows the older, 
18630 62 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f  buggy applicatio
18640 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a  n code to work.*
18650 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65  * without change
18660 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72   even with newer
18670 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
18680 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ite..**.** [[SQL
18690 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
186a0 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  E]] [[SQLITE_CON
186b0 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a  FIG_GETPCACHE]].
186c0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
186d0 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20  NFIG_PCACHE and 
186e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
186f0 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20  TPCACHE.** <dd> 
18700 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72  These options ar
18710 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73  e obsolete and s
18720 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
18730 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a  d by new code..*
18740 2a 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69  * They are retai
18750 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ned for backward
18760 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
18770 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f  but are now no-o
18780 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a  ps..** </dd>.**.
18790 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
187a0 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c  IG_SQLLOG]].** <
187b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
187c0 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54  _SQLLOG.** <dd>T
187d0 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e  his option is on
187e0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
187f0 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  sqlite is compil
18800 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ed with the.** [
18810 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51  SQLITE_ENABLE_SQ
18820 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63 65 73  LLOG] pre-proces
18830 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69 6e 65  sor macro define
18840 64 2e 20 54 68 65 20 66 69 72 73 74 20 61 72 67  d. The first arg
18850 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20  ument should.** 
18860 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
18870 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79  a function of ty
18880 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  pe void(*)(void*
18890 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20  ,sqlite3*,const 
188a0 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20  char*, int)..** 
188b0 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c  The second shoul
188c0 64 20 62 65 20 6f 66 20 74 79 70 65 20 28 76 6f  d be of type (vo
188d0 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c 62 61  id*). The callba
188e0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  ck is invoked by
188f0 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20   the library.** 
18900 69 6e 20 74 68 72 65 65 20 73 65 70 61 72 61 74  in three separat
18910 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2c  e circumstances,
18920 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
18930 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  he value passed 
18940 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
18950 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66 20 74   parameter. If t
18960 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
18970 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e 20 74  ter is 0, then t
18980 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
18990 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64  ection.** passed
189a0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
189b0 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75 73 74  rgument has just
189c0 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68   been opened. Th
189d0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
189e0 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  .** points to a 
189f0 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e  buffer containin
18a00 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  g the name of th
18a10 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
18a20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20  file. If the.** 
18a30 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
18a40 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68 65 20   is 1, then the 
18a50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68  SQL statement th
18a60 61 74 20 74 68 65 20 74 68 69 72 64 20 70 61 72  at the third par
18a70 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73  ameter.** points
18a80 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62 65 65   to has just bee
18a90 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72 2c 20  n executed. Or, 
18aa0 69 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  if the fourth pa
18ab0 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20 74 68  rameter is 2, th
18ac0 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63  en.** the connec
18ad0 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73 73 65  tion being passe
18ae0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
18af0 70 61 72 61 6d 65 74 65 72 20 69 73 20 62 65 69  parameter is bei
18b00 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a  ng closed. The.*
18b10 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
18b20 72 20 69 73 20 70 61 73 73 65 64 20 4e 55 4c 4c  r is passed NULL
18b30 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e 20 20   In this case.  
18b40 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 75 73  An example of us
18b50 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66  ing this.** conf
18b60 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
18b70 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69 6e 20   can be seen in 
18b80 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67  the "test_sqllog
18b90 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c 65 20  .c" source file 
18ba0 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69  in.** the canoni
18bb0 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75 72 63  cal SQLite sourc
18bc0 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a  e tree.</dd>.**.
18bd0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
18be0 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a  IG_MMAP_SIZE]].*
18bf0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
18c00 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a  FIG_MMAP_SIZE.**
18c10 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e   <dd>^SQLITE_CON
18c20 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61  FIG_MMAP_SIZE ta
18c30 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74 20 69  kes two 64-bit i
18c40 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65 33 5f  nteger (sqlite3_
18c50 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a  int64) values.**
18c60 20 74 68 61 74 20 61 72 65 20 74 68 65 20 64 65   that are the de
18c70 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20  fault mmap size 
18c80 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66 61 75  limit (the defau
18c90 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a  lt setting for.*
18ca0 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  * [PRAGMA mmap_s
18cb0 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20 6d 61  ize]) and the ma
18cc0 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d  ximum allowed mm
18cd0 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a  ap size limit..*
18ce0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 73  * ^The default s
18cf0 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20 6f 76  etting can be ov
18d00 65 72 72 69 64 64 65 6e 20 62 79 20 65 61 63 68  erridden by each
18d10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18d20 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69  tion using.** ei
18d30 74 68 65 72 20 74 68 65 20 5b 50 52 41 47 4d 41  ther the [PRAGMA
18d40 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d   mmap_size] comm
18d50 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69 6e 67  and, or by using
18d60 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
18d70 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d  FCNTL_MMAP_SIZE]
18d80 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20   file control.  
18d90 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  ^(The maximum al
18da0 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a  lowed mmap size.
18db0 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e  ** will be silen
18dc0 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 69 66  tly truncated if
18dd0 20 6e 65 63 65 73 73 61 72 79 20 73 6f 20 74 68   necessary so th
18de0 61 74 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 65  at it does not e
18df0 78 63 65 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  xceed the.** com
18e00 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75  pile-time maximu
18e10 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20  m mmap size set 
18e20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
18e30 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d  E_MAX_MMAP_SIZE]
18e40 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
18e50 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65  tion.)^.** ^If e
18e60 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74  ither argument t
18e70 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  o this option is
18e80 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
18e90 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73  that argument is
18ea0 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69  .** changed to i
18eb0 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ts compile-time 
18ec0 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b  default..**.** [
18ed0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  [SQLITE_CONFIG_W
18ee0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a  IN32_HEAPSIZE]].
18ef0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
18f00 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
18f10 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20  IZE.** <dd>^The 
18f20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
18f30 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 6f 70 74  N32_HEAPSIZE opt
18f40 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
18f50 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
18f60 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66  is.** compiled f
18f70 6f 72 20 57 69 6e 64 6f 77 73 20 77 69 74 68 20  or Windows with 
18f80 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33  the [SQLITE_WIN3
18f90 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72  2_MALLOC] pre-pr
18fa0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a  ocessor macro.**
18fb0 20 64 65 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54   defined. ^SQLIT
18fc0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
18fd0 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20  EAPSIZE takes a 
18fe0 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  32-bit unsigned 
18ff0 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a  integer value.**
19000 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20   that specifies 
19010 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65  the maximum size
19020 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20   of the created 
19030 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  heap..**.** [[SQ
19040 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
19050 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64  HE_HDRSZ]].** <d
19060 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
19070 50 43 41 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20  PCACHE_HDRSZ.** 
19080 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
19090 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
190a0 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  RSZ option takes
190b0 20 61 20 73 69 6e 67 6c 65 20 70 61 72 61 6d 65   a single parame
190c0 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20  ter which.** is 
190d0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
190e0 69 6e 74 65 67 65 72 20 61 6e 64 20 77 72 69 74  integer and writ
190f0 65 73 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  es into that int
19100 65 67 65 72 20 74 68 65 20 6e 75 6d 62 65 72 20  eger the number 
19110 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62 79 74 65  of extra.** byte
19120 73 20 70 65 72 20 70 61 67 65 20 72 65 71 75 69  s per page requi
19130 72 65 64 20 66 6f 72 20 65 61 63 68 20 70 61 67  red for each pag
19140 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  e in [SQLITE_CON
19150 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
19160 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66  ** The amount of
19170 20 65 78 74 72 61 20 73 70 61 63 65 20 72 65 71   extra space req
19180 75 69 72 65 64 20 63 61 6e 20 63 68 61 6e 67 65  uired can change
19190 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
191a0 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74  e compiler,.** t
191b0 61 72 67 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20  arget platform, 
191c0 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
191d0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  on..**.** [[SQLI
191e0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d  TE_CONFIG_PMASZ]
191f0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
19200 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20  CONFIG_PMASZ.** 
19210 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f  <dd>^The SQLITE_
19220 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74  CONFIG_PMASZ opt
19230 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
19240 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69  le parameter whi
19250 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69  ch.** is an unsi
19260 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
19270 20 73 65 74 73 20 74 68 65 20 22 4d 69 6e 69 6d   sets the "Minim
19280 75 6d 20 50 4d 41 20 53 69 7a 65 22 20 66 6f 72  um PMA Size" for
19290 20 74 68 65 20 6d 75 6c 74 69 74 68 72 65 61 64   the multithread
192a0 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20  ed.** sorter to 
192b0 74 68 61 74 20 69 6e 74 65 67 65 72 2e 20 20 54  that integer.  T
192c0 68 65 20 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d  he default minim
192d0 75 6d 20 50 4d 41 20 53 69 7a 65 20 69 73 20 73  um PMA Size is s
192e0 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
192f0 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53  LITE_SORTER_PMAS
19300 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  Z] compile-time 
19310 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72  option.  New thr
19320 65 61 64 73 20 61 72 65 20 6c 61 75 6e 63 68 65  eads are launche
19330 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20 77 69 74  d.** to help wit
19340 68 20 73 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e  h sort operation
19350 73 20 77 68 65 6e 20 6d 75 6c 74 69 74 68 72 65  s when multithre
19360 61 64 65 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20  aded sorting.** 
19370 69 73 20 65 6e 61 62 6c 65 64 20 28 75 73 69 6e  is enabled (usin
19380 67 20 74 68 65 20 5b 50 52 41 47 4d 41 20 74 68  g the [PRAGMA th
19390 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20  reads] command) 
193a0 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  and the amount o
193b0 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20  f content.** to 
193c0 62 65 20 73 6f 72 74 65 64 20 65 78 63 65 65 64  be sorted exceed
193d0 73 20 74 68 65 20 70 61 67 65 20 73 69 7a 65 20  s the page size 
193e0 74 69 6d 65 73 20 74 68 65 20 6d 69 6e 69 6d 75  times the minimu
193f0 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41  m of the.** [PRA
19400 47 4d 41 20 63 61 63 68 65 5f 73 69 7a 65 5d 20  GMA cache_size] 
19410 73 65 74 74 69 6e 67 20 61 6e 64 20 74 68 69 73  setting and this
19420 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   value..**.** [[
19430 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54  SQLITE_CONFIG_ST
19440 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 5d 0a 2a  MTJRNL_SPILL]].*
19450 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
19460 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
19470 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53  LL.** <dd>^The S
19480 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 54 4d  QLITE_CONFIG_STM
19490 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f 70 74 69  TJRNL_SPILL opti
194a0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
194b0 65 20 70 61 72 61 6d 65 74 65 72 20 77 68 69 63  e parameter whic
194c0 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20 74 68 65  h.** becomes the
194d0 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a 6f 75 72   [statement jour
194e0 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f 2d 64 69  nal] spill-to-di
194f0 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e 20 20 0a  sk threshold.  .
19500 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74 20 6a 6f  ** [Statement jo
19510 75 72 6e 61 6c 73 5d 20 61 72 65 20 68 65 6c 64  urnals] are held
19520 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e 74 69 6c   in memory until
19530 20 74 68 65 69 72 20 73 69 7a 65 20 28 69 6e 20   their size (in 
19540 62 79 74 65 73 29 0a 2a 2a 20 65 78 63 65 65 64  bytes).** exceed
19550 73 20 74 68 69 73 20 74 68 72 65 73 68 6f 6c 64  s this threshold
19560 2c 20 61 74 20 77 68 69 63 68 20 70 6f 69 6e 74  , at which point
19570 20 74 68 65 79 20 61 72 65 20 77 72 69 74 74 65   they are writte
19580 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a 20 4f 72  n to disk..** Or
19590 20 69 66 20 74 68 65 20 74 68 72 65 73 68 6f 6c   if the threshol
195a0 64 20 69 73 20 2d 31 2c 20 73 74 61 74 65 6d 65  d is -1, stateme
195b0 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61 72 65 20  nt journals are 
195c0 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a 2a 20 65  always held.** e
195d0 78 63 6c 75 73 69 76 65 6c 79 20 69 6e 20 6d 65  xclusively in me
195e0 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63 65 20 6d  mory..** Since m
195f0 61 6e 79 20 73 74 61 74 65 6d 65 6e 74 20 6a 6f  any statement jo
19600 75 72 6e 61 6c 73 20 6e 65 76 65 72 20 62 65 63  urnals never bec
19610 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65 74 74 69  ome large, setti
19620 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a 2a 2a 20  ng the spill.** 
19630 74 68 72 65 73 68 6f 6c 64 20 74 6f 20 61 20 76  threshold to a v
19640 61 6c 75 65 20 73 75 63 68 20 61 73 20 36 34 4b  alue such as 64K
19650 69 42 20 63 61 6e 20 67 72 65 61 74 6c 79 20 72  iB can greatly r
19660 65 64 75 63 65 20 74 68 65 20 61 6d 6f 75 6e 74  educe the amount
19670 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65 71 75 69   of.** I/O requi
19680 72 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 73  red to support s
19690 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c 62 61 63  tatement rollbac
196a0 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c  k..** The defaul
196b0 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 69 73  t value for this
196c0 20 73 65 74 74 69 6e 67 20 69 73 20 63 6f 6e 74   setting is cont
196d0 72 6f 6c 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a  rolled by the.**
196e0 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54 4a 52 4e   [SQLITE_STMTJRN
196f0 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70 69 6c 65  L_SPILL] compile
19700 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  -time option..**
19710 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
19720 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19730 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
19740 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
19750 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
19760 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
19770 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
19780 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
19790 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
197a0 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
197b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
197c0 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
197d0 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
197e0 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
197f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
19800 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
19810 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
19820 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
19830 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19840 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
19850 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
19860 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
19870 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19880 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
19890 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
198a0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
198b0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
198c0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
198d0 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
198e0 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
198f0 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
19900 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
19910 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
19920 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
19930 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19940 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
19950 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
19960 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
19970 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
19980 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
19990 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
199a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
199b0 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
199c0 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
199d0 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
199e0 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
199f0 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
19a00 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
19a10 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
19a20 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
19a30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19a40 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
19a50 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
19a60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19a70 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
19a80 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
19a90 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
19aa0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
19ab0 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
19ac0 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
19ad0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19ae0 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
19af0 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
19b00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19b10 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
19b20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
19b30 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
19b40 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
19b50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
19b60 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
19b70 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
19b80 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
19b90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
19ba0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
19bb0 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69  EX_SCAN 20  /* i
19bc0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
19bd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
19be0 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20  OG       21  /* 
19bf0 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a  xSqllog, void* *
19c00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19c10 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
19c20 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69  E    22  /* sqli
19c30 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74  te3_int64, sqlit
19c40 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66  e3_int64 */.#def
19c50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
19c60 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
19c70 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74        23  /* int
19c80 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e   nByte */.#defin
19c90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19ca0 50 43 41 43 48 45 5f 48 44 52 53 5a 20 20 20 20  PCACHE_HDRSZ    
19cb0 20 20 20 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a      24  /* int *
19cc0 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  psz */.#define S
19cd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
19ce0 53 5a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  SZ              
19cf0 20 32 35 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64   25  /* unsigned
19d00 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f 0a 23 64   int szPma */.#d
19d10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
19d20 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49  FIG_STMTJRNL_SPI
19d30 4c 4c 20 20 20 20 20 20 32 36 20 20 2f 2a 20 69  LL      26  /* i
19d40 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a  nt nByte */../*.
19d50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
19d60 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
19d70 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
19d80 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
19d90 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
19da0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
19db0 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
19dc0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
19dd0 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
19de0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
19df0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
19e00 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
19e10 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
19e20 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
19e30 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
19e40 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
19e50 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
19e60 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
19e70 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
19e80 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
19e90 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
19ea0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
19eb0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
19ec0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
19ed0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
19ee0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
19ef0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
19f00 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
19f10 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
19f20 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
19f30 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
19f40 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
19f50 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
19f60 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
19f70 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
19f80 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
19f90 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
19fa0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
19fb0 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
19fc0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
19fd0 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
19fe0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
19ff0 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
1a000 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
1a010 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
1a020 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
1a030 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
1a040 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
1a050 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
1a060 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
1a070 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1a080 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
1a090 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
1a0a0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
1a0b0 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
1a0c0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
1a0d0 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
1a0e0 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
1a0f0 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
1a100 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
1a110 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
1a120 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
1a130 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
1a140 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
1a150 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
1a160 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
1a170 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
1a180 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
1a190 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
1a1a0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
1a1b0 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
1a1c0 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
1a1d0 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
1a1e0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
1a1f0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
1a200 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
1a210 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
1a220 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
1a230 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1a240 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
1a250 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
1a260 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
1a270 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
1a280 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
1a290 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
1a2a0 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
1a2b0 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
1a2c0 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
1a2d0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1a2e0 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
1a2f0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
1a300 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
1a310 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
1a320 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
1a330 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
1a340 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d  e next smaller m
1a350 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e  ultiple of 8.  ^
1a360 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  (The lookaside m
1a370 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75  emory.** configu
1a380 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74  ration for a dat
1a390 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a3a0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61   can only be cha
1a3b0 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a  nged when that.*
1a3c0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
1a3d0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73  not currently us
1a3e0 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ing lookaside me
1a3f0 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65  mory, or in othe
1a400 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20  r words.** when 
1a410 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c  the "current val
1a420 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ue" returned by.
1a430 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73  ** [sqlite3_db_s
1a440 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45  tatus](D,[SQLITE
1a450 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
1a460 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e  E],...) is zero.
1a470 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
1a480 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
1a490 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63  okaside memory c
1a4a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65  onfiguration whe
1a4b0 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d  n lookaside.** m
1a4c0 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20  emory is in use 
1a4d0 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69  leaves the confi
1a4e0 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67  guration unchang
1a4f0 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a  ed and returns .
1a500 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1a510 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  .)^</dd>.**.** <
1a520 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
1a530 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f  IG_ENABLE_FKEY</
1a540 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
1a550 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
1a560 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
1a570 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63  sable the enforc
1a580 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72  ement of.** [for
1a590 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
1a5a0 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68  ints].  There sh
1a5b0 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
1a5c0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
1a5d0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
1a5e0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
1a5f0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
1a600 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65   to disable FK e
1a610 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70  nforcement,.** p
1a620 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
1a630 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
1a640 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
1a650 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65  leave FK enforce
1a660 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ment.** unchange
1a670 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  d.  The second p
1a680 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
1a690 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
1a6a0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
1a6b0 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
1a6c0 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
1a6d0 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72  whether FK enfor
1a6e0 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72  cement is off or
1a6f0 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67   on.** following
1a700 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
1a710 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a720 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
1a730 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
1a740 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b  hich case the FK
1a750 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74   enforcement set
1a760 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
1a770 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
1a780 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
1a790 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1a7a0 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a  E_TRIGGER</dt>.*
1a7b0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
1a7c0 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
1a7d0 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
1a7e0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
1a7f0 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a   | triggers]..**
1a800 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
1a810 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
1a820 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
1a830 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
1a840 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
1a850 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
1a860 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a  able triggers,.*
1a870 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
1a880 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72  able triggers or
1a890 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
1a8a0 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
1a8b0 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
1a8c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1a8d0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
1a8e0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
1a8f0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
1a900 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
1a910 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
1a920 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69   triggers are di
1a930 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
1a940 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
1a950 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
1a960 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1a970 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
1a980 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
1a990 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67  ch case the trig
1a9a0 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ger setting is n
1a9b0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
1a9c0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
1a9d0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
1a9e0 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33 5f 54 4f  G_ENABLE_FTS3_TO
1a9f0 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a 2a 2a 20  KENIZER</dt>.** 
1aa00 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
1aa10 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
1aa20 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
1aa30 68 65 20 74 77 6f 2d 61 72 67 75 6d 65 6e 74 0a  he two-argument.
1aa40 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ** version of th
1aa50 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65  e [fts3_tokenize
1aa60 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 77 68  r()] function wh
1aa70 69 63 68 20 69 73 20 70 61 72 74 20 6f 66 20 74  ich is part of t
1aa80 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20 66 75 6c  he.** [FTS3] ful
1aa90 6c 2d 74 65 78 74 20 73 65 61 72 63 68 20 65 6e  l-text search en
1aaa0 67 69 6e 65 20 65 78 74 65 6e 73 69 6f 6e 2e 0a  gine extension..
1aab0 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
1aac0 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
1aad0 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
1aae0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1aaf0 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  nt is an integer
1ab00 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64   which is 0 to d
1ab10 69 73 61 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65  isable fts3_toke
1ab20 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a 20 70 6f  nizer() or.** po
1ab30 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
1ab40 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a 65 72 28   fts3_tokenizer(
1ab50 29 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  ) or negative to
1ab60 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
1ab70 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  ng.** unchanged.
1ab80 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
1ab90 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
1aba0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
1abb0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
1abc0 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
1abd0 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
1abe0 77 68 65 74 68 65 72 20 66 74 73 33 5f 74 6f 6b  whether fts3_tok
1abf0 65 6e 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c  enizer is disabl
1ac00 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a  ed or enabled.**
1ac10 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
1ac20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
1ac30 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
1ac40 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
1ac50 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
1ac60 61 73 65 20 74 68 65 20 6e 65 77 20 73 65 74 74  ase the new sett
1ac70 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
1ac80 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
1ac90 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
1aca0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
1acb0 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49 4f 4e 3c  _LOAD_EXTENSION<
1acc0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
1acd0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
1ace0 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
1acf0 69 73 61 62 6c 65 20 74 68 65 20 5b 73 71 6c 69  isable the [sqli
1ad00 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  te3_load_extensi
1ad10 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  on()].** interfa
1ad20 63 65 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79  ce independently
1ad30 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78   of the [load_ex
1ad40 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51 4c 20 66  tension()] SQL f
1ad50 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20  unction..** The 
1ad60 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
1ad70 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
1ad80 5d 20 41 50 49 20 65 6e 61 62 6c 65 73 20 6f 72  ] API enables or
1ad90 20 64 69 73 61 62 6c 65 73 20 62 6f 74 68 20 74   disables both t
1ada0 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b 73 71 6c  he.** C-API [sql
1adb0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
1adc0 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68 65 20 53  ion()] and the S
1add0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b 6c 6f 61  QL function [loa
1ade0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a  d_extension()]..
1adf0 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20  ** There should 
1ae00 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61  be two additiona
1ae10 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20  l arguments..** 
1ae20 57 68 65 6e 20 74 68 65 20 66 69 72 73 74 20 61  When the first a
1ae30 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69 73 20  rgument to this 
1ae40 69 6e 74 65 72 66 61 63 65 20 69 73 20 31 2c 20  interface is 1, 
1ae50 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65 20 43 2d  then only the C-
1ae60 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61 62 6c 65  API is.** enable
1ae70 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  d and the SQL fu
1ae80 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 64  nction remains d
1ae90 69 73 61 62 6c 65 64 2e 20 20 49 66 20 74 68 65  isabled.  If the
1aea0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
1aeb0 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72  to.** this inter
1aec0 66 61 63 65 20 69 73 20 30 2c 20 74 68 65 6e 20  face is 0, then 
1aed0 62 6f 74 68 20 74 68 65 20 43 2d 41 50 49 20 61  both the C-API a
1aee0 6e 64 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nd the SQL funct
1aef0 69 6f 6e 20 61 72 65 20 64 69 73 61 62 6c 65 64  ion are disabled
1af00 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73  ..** If the firs
1af10 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 2d 31  t argument is -1
1af20 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65  , then no change
1af30 73 20 61 72 65 20 6d 61 64 65 20 74 6f 20 73 74  s are made to st
1af40 61 74 65 20 6f 66 20 65 69 74 68 65 72 20 74 68  ate of either th
1af50 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72 20 74 68  e.** C-API or th
1af60 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a  e SQL function..
1af70 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
1af80 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
1af90 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
1afa0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
1afb0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
1afc0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
1afd0 68 65 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  hether [sqlite3_
1afe0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
1aff0 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69  ] interface.** i
1b000 73 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  s disabled or en
1b010 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20  abled following 
1b020 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
1b030 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1b040 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20 4e 55 4c   may.** be a NUL
1b050 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 20 77 68  L pointer, in wh
1b060 69 63 68 20 63 61 73 65 20 74 68 65 20 6e 65 77  ich case the new
1b070 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
1b080 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 0a 2a  reported back..*
1b090 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  * </dd>.**.** <d
1b0a0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
1b0b0 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c 2f 64 74  G_MAINDBNAME</dt
1b0c0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
1b0d0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
1b0e0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6e 61 6d  o change the nam
1b0f0 65 20 6f 66 20 74 68 65 20 22 6d 61 69 6e 22 20  e of the "main" 
1b100 64 61 74 61 62 61 73 65 0a 2a 2a 20 73 63 68 65  database.** sche
1b110 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c 65 20 61  ma.  ^The sole a
1b120 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
1b130 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e 73 74 61  nter to a consta
1b140 6e 74 20 55 54 46 38 20 73 74 72 69 6e 67 0a 2a  nt UTF8 string.*
1b150 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 63  * which will bec
1b160 6f 6d 65 20 74 68 65 20 6e 65 77 20 73 63 68 65  ome the new sche
1b170 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c 61 63 65  ma name in place
1b180 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20 5e 53 51   of "main".  ^SQ
1b190 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  Lite.** does not
1b1a0 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
1b1b0 74 68 65 20 6e 65 77 20 6d 61 69 6e 20 73 63 68  the new main sch
1b1c0 65 6d 61 20 6e 61 6d 65 20 73 74 72 69 6e 67 2c  ema name string,
1b1d0 20 73 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   so the applicat
1b1e0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75  ion.** must ensu
1b1f0 72 65 20 74 68 61 74 20 74 68 65 20 61 72 67 75  re that the argu
1b200 6d 65 6e 74 20 70 61 73 73 65 64 20 69 6e 74 6f  ment passed into
1b210 20 74 68 69 73 20 44 42 43 4f 4e 46 49 47 20 6f   this DBCONFIG o
1b220 70 74 69 6f 6e 20 69 73 20 75 6e 63 68 61 6e 67  ption is unchang
1b230 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61 66 74 65  ed.** until afte
1b240 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  r the database c
1b250 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
1b260 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
1b270 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
1b280 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f  NFIG_NO_CKPT_ON_
1b290 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CLOSE</dt>.** <d
1b2a0 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77 68 65 6e  d> Usually, when
1b2b0 20 61 20 64 61 74 61 62 61 73 65 20 69 6e 20 77   a database in w
1b2c0 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c 6f 73 65  al mode is close
1b2d0 64 20 6f 72 20 64 65 74 61 63 68 65 64 20 66 72  d or detached fr
1b2e0 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61 62 61 73  om a .** databas
1b2f0 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c 69 74 65  e handle, SQLite
1b300 20 63 68 65 63 6b 73 20 69 66 20 74 68 69 73 20   checks if this 
1b310 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61 74 20 74  will mean that t
1b320 68 65 72 65 20 61 72 65 20 6e 6f 77 20 6e 6f 20  here are now no 
1b330 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  .** connections 
1b340 61 74 20 61 6c 6c 20 74 6f 20 74 68 65 20 64 61  at all to the da
1b350 74 61 62 61 73 65 2e 20 49 66 20 73 6f 2c 20 69  tabase. If so, i
1b360 74 20 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65  t performs a che
1b370 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f 70 65 72  ckpoint .** oper
1b380 61 74 69 6f 6e 20 62 65 66 6f 72 65 20 63 6c 6f  ation before clo
1b390 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e 65 63 74  sing the connect
1b3a0 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74 69 6f 6e  ion. This option
1b3b0 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 0a   may be used to.
1b3c0 2a 2a 20 6f 76 65 72 72 69 64 65 20 74 68 69 73  ** override this
1b3d0 20 62 65 68 61 76 69 6f 75 72 2e 20 54 68 65 20   behaviour. The 
1b3e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1b3f0 70 61 73 73 65 64 20 74 6f 20 74 68 69 73 20 6f  passed to this o
1b400 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 61  peration.** is a
1b410 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e 6f 6e 2d  n integer - non-
1b420 7a 65 72 6f 20 74 6f 20 64 69 73 61 62 6c 65 20  zero to disable 
1b430 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f 6e 2d 63  checkpoints-on-c
1b440 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f 20 28 74  lose, or zero (t
1b450 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 29 20 74  he.** default) t
1b460 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d 2e 20 54  o enable them. T
1b470 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1b480 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
1b490 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   to an integer.*
1b4a0 2a 20 69 6e 74 6f 20 77 68 69 63 68 20 69 73 20  * into which is 
1b4b0 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74  written 0 or 1 t
1b4c0 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68  o indicate wheth
1b4d0 65 72 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  er checkpoints-o
1b4e0 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61 76 65 20  n-close.** have 
1b4f0 62 65 65 6e 20 64 69 73 61 62 6c 65 64 20 2d 20  been disabled - 
1b500 30 20 69 66 20 74 68 65 79 20 61 72 65 20 6e 6f  0 if they are no
1b510 74 20 64 69 73 61 62 6c 65 64 2c 20 31 20 69 66  t disabled, 1 if
1b520 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a 20 3c 2f   they are..** </
1b530 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a  dd>.**.** </dl>.
1b540 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b550 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41 49 4e 44  E_DBCONFIG_MAIND
1b560 42 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20  BNAME           
1b570 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73 74 20 63   1000 /* const c
1b580 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  har* */.#define 
1b590 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
1b5a0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20  LOOKASIDE       
1b5b0 20 20 20 20 20 20 31 30 30 31 20 2f 2a 20 76 6f        1001 /* vo
1b5c0 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
1b5d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
1b5e0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
1b5f0 45 59 20 20 20 20 20 20 20 20 20 20 20 31 30 30  EY           100
1b600 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f  2 /* int int* */
1b610 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b620 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
1b630 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 31  TRIGGER        1
1b640 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  003 /* int int* 
1b650 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b660 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
1b670 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49 5a 45 52  E_FTS3_TOKENIZER
1b680 20 31 30 30 34 20 2f 2a 20 69 6e 74 20 69 6e 74   1004 /* int int
1b690 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
1b6a0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
1b6b0 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
1b6c0 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e 74 20 69  ON 1005 /* int i
1b6d0 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
1b6e0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4e  QLITE_DBCONFIG_N
1b6f0 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f 53 45 20  O_CKPT_ON_CLOSE 
1b700 20 20 20 20 20 31 30 30 36 20 2f 2a 20 69 6e 74       1006 /* int
1b710 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
1b720 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
1b730 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
1b740 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
1b750 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
1b760 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lite3.**.** ^The
1b770 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1b780 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
1b790 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
1b7a0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
1b7b0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1b7c0 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
1b7d0 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
1b7e0 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
1b7f0 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
1b800 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1b810 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
1b820 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
1b830 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  y..*/.SQLITE_API
1b840 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
1b850 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
1b860 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
1b870 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
1b880 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
1b890 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 20 4d  nsert Rowid.** M
1b8a0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
1b8b0 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79  *.** ^Each entry
1b8c0 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20   in most SQLite 
1b8d0 74 61 62 6c 65 73 20 28 65 78 63 65 70 74 20 66  tables (except f
1b8e0 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49  or [WITHOUT ROWI
1b8f0 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61  D] tables).** ha
1b900 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
1b910 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
1b920 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
1b930 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
1b940 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
1b950 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
1b960 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
1b970 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
1b980 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
1b990 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
1b9a0 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
1b9b0 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
1b9c0 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
1b9d0 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
1b9e0 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
1b9f0 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
1ba00 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
1ba10 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
1ba20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
1ba30 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
1ba40 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
1ba50 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
1ba60 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  The sqlite3_last
1ba70 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29  _insert_rowid(D)
1ba80 20 69 6e 74 65 72 66 61 63 65 20 75 73 75 61 6c   interface usual
1ba90 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ly returns the [
1baa0 72 6f 77 69 64 5d 20 6f 66 0a 2a 2a 20 74 68 65  rowid] of.** the
1bab0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
1bac0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
1bad0 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61   into a rowid ta
1bae0 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ble or [virtual 
1baf0 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74  table].** on dat
1bb00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1bb10 20 44 2e 20 5e 49 6e 73 65 72 74 73 20 69 6e 74   D. ^Inserts int
1bb20 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44  o [WITHOUT ROWID
1bb30 5d 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74  ] tables are not
1bb40 0a 2a 2a 20 72 65 63 6f 72 64 65 64 2e 20 5e 49  .** recorded. ^I
1bb50 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
1bb60 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72  [INSERT]s into r
1bb70 6f 77 69 64 20 74 61 62 6c 65 73 20 68 61 76 65  owid tables have
1bb80 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 0a   ever occurred .
1bb90 2a 2a 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  ** on the databa
1bba0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c  se connection D,
1bbb0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61   then sqlite3_la
1bbc0 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
1bbd0 44 29 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 7a  D) returns .** z
1bbe0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 41 73 20 77 65  ero..**.** As we
1bbf0 6c 6c 20 61 73 20 62 65 69 6e 67 20 73 65 74 20  ll as being set 
1bc00 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 73  automatically as
1bc10 20 72 6f 77 73 20 61 72 65 20 69 6e 73 65 72 74   rows are insert
1bc20 65 64 20 69 6e 74 6f 20 64 61 74 61 62 61 73 65  ed into database
1bc30 0a 2a 2a 20 74 61 62 6c 65 73 2c 20 74 68 65 20  .** tables, the 
1bc40 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1bc50 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  y this function 
1bc60 6d 61 79 20 62 65 20 73 65 74 20 65 78 70 6c 69  may be set expli
1bc70 63 69 74 6c 79 20 62 79 0a 2a 2a 20 5b 73 71 6c  citly by.** [sql
1bc80 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69 6e  ite3_set_last_in
1bc90 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
1bca0 0a 2a 2a 20 53 6f 6d 65 20 76 69 72 74 75 61 6c  .** Some virtual
1bcb0 20 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74   table implement
1bcc0 61 74 69 6f 6e 73 20 6d 61 79 20 49 4e 53 45 52  ations may INSER
1bcd0 54 20 72 6f 77 73 20 69 6e 74 6f 20 72 6f 77 69  T rows into rowi
1bce0 64 20 74 61 62 6c 65 73 20 61 73 0a 2a 2a 20 70  d tables as.** p
1bcf0 61 72 74 20 6f 66 20 63 6f 6d 6d 69 74 74 69 6e  art of committin
1bd00 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
1bd10 28 65 2e 67 2e 20 74 6f 20 66 6c 75 73 68 20 64  (e.g. to flush d
1bd20 61 74 61 20 61 63 63 75 6d 75 6c 61 74 65 64 20  ata accumulated 
1bd30 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 74 6f 20  in memory.** to 
1bd40 64 69 73 6b 29 2e 20 49 6e 20 74 68 69 73 20 63  disk). In this c
1bd50 61 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 63  ase subsequent c
1bd60 61 6c 6c 73 20 74 6f 20 74 68 69 73 20 66 75 6e  alls to this fun
1bd70 63 74 69 6f 6e 20 72 65 74 75 72 6e 20 74 68 65  ction return the
1bd80 20 72 6f 77 69 64 0a 2a 2a 20 61 73 73 6f 63 69   rowid.** associ
1bd90 61 74 65 64 20 77 69 74 68 20 74 68 65 73 65 20  ated with these 
1bda0 69 6e 74 65 72 6e 61 6c 20 49 4e 53 45 52 54 20  internal INSERT 
1bdb0 6f 70 65 72 61 74 69 6f 6e 73 2c 20 77 68 69 63  operations, whic
1bdc0 68 20 6c 65 61 64 73 20 74 6f 20 0a 2a 2a 20 75  h leads to .** u
1bdd0 6e 69 6e 74 75 69 74 69 76 65 20 72 65 73 75 6c  nintuitive resul
1bde0 74 73 2e 20 56 69 72 74 75 61 6c 20 74 61 62 6c  ts. Virtual tabl
1bdf0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1be00 73 20 74 68 61 74 20 64 6f 20 77 72 69 74 65 20  s that do write 
1be10 74 6f 20 72 6f 77 69 64 0a 2a 2a 20 74 61 62 6c  to rowid.** tabl
1be20 65 73 20 69 6e 20 74 68 69 73 20 77 61 79 20 63  es in this way c
1be30 61 6e 20 61 76 6f 69 64 20 74 68 69 73 20 70 72  an avoid this pr
1be40 6f 62 6c 65 6d 20 62 79 20 72 65 73 74 6f 72 69  oblem by restori
1be50 6e 67 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  ng the original 
1be60 0a 2a 2a 20 72 6f 77 69 64 20 76 61 6c 75 65 20  .** rowid value 
1be70 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
1be80 65 74 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  et_last_insert_r
1be90 6f 77 69 64 28 29 5d 20 62 65 66 6f 72 65 20 72  owid()] before r
1bea0 65 74 75 72 6e 69 6e 67 20 0a 2a 2a 20 63 6f 6e  eturning .** con
1beb0 74 72 6f 6c 20 74 6f 20 74 68 65 20 75 73 65 72  trol to the user
1bec0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
1bed0 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
1bee0 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
1bef0 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
1bf00 6e 65 20 77 69 6c 6c 20 0a 2a 2a 20 72 65 74 75  ne will .** retu
1bf10 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
1bf20 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 20 72  f the inserted r
1bf30 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68  ow as long as th
1bf40 65 20 74 72 69 67 67 65 72 20 69 73 20 0a 2a 2a  e trigger is .**
1bf50 20 72 75 6e 6e 69 6e 67 2e 20 4f 6e 63 65 20 74   running. Once t
1bf60 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  he trigger progr
1bf70 61 6d 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  am ends, the val
1bf80 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
1bf90 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
1bfa0 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
1bfb0 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
1bfc0 65 20 74 72 69 67 67 65 72 20 77 61 73 20 66 69  e trigger was fi
1bfd0 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  red.)^.**.** ^An
1bfe0 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66   [INSERT] that f
1bff0 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f  ails due to a co
1c000 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
1c010 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73  on is not a.** s
1c020 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
1c030 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  T] and does not 
1c040 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
1c050 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
1c060 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e  s.** routine.  ^
1c070 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46  Thus INSERT OR F
1c080 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49  AIL, INSERT OR I
1c090 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52  GNORE, INSERT OR
1c0a0 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e   ROLLBACK,.** an
1c0b0 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52  d INSERT OR ABOR
1c0c0 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65  T make no change
1c0d0 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20  s to the return 
1c0e0 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a  value of this.**
1c0f0 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68   routine when th
1c100 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61  eir insertion fa
1c110 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53  ils.  ^(When INS
1c120 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a  ERT OR REPLACE.*
1c130 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63  * encounters a c
1c140 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
1c150 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74  ion, it does not
1c160 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49   fail.  The.** I
1c170 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20  NSERT continues 
1c180 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66  to completion af
1c190 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77  ter deleting row
1c1a0 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a  s that caused.**
1c1b0 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20   the constraint 
1c1c0 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52  problem so INSER
1c1d0 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c  T OR REPLACE wil
1c1e0 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a  l always change.
1c1f0 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ** the return va
1c200 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  lue of this inte
1c210 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  rface.)^.**.** ^
1c220 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
1c230 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
1c240 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73  , an [INSERT] is
1c250 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a   considered to.*
1c260 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20  * be successful 
1c270 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75  even if it is su
1c280 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65  bsequently rolle
1c290 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
1c2a0 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  is function is a
1c2b0 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c  ccessible to SQL
1c2c0 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20   statements via 
1c2d0 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73  the.** [last_ins
1c2e0 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20  ert_rowid() SQL 
1c2f0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1c300 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1c310 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61  hread performs a
1c320 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e   new [INSERT] on
1c330 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74   the same.** dat
1c340 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c350 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69   while the [sqli
1c360 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1c370 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63  rowid()].** func
1c380 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20  tion is running 
1c390 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73  and thus changes
1c3a0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
1c3b0 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65   [rowid],.** the
1c3c0 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
1c3d0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1c3e0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
1c3f0 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72  id()] is.** unpr
1c400 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69  edictable and mi
1c410 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69  ght not equal ei
1c420 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20  ther the old or 
1c430 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20  the new.** last 
1c440 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a  insert [rowid]..
1c450 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
1c460 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
1c470 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1c480 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b  rowid(sqlite3*);
1c490 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c4a0 3a 20 53 65 74 20 74 68 65 20 4c 61 73 74 20 49  : Set the Last I
1c4b0 6e 73 65 72 74 20 52 6f 77 69 64 20 76 61 6c 75  nsert Rowid valu
1c4c0 65 2e 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  e..** METHOD: sq
1c4d0 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
1c4e0 73 71 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74  sqlite3_set_last
1c4f0 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 2c  _insert_rowid(D,
1c500 20 52 29 20 6d 65 74 68 6f 64 20 61 6c 6c 6f 77   R) method allow
1c510 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
1c520 6e 20 74 6f 0a 2a 2a 20 73 65 74 20 74 68 65 20  n to.** set the 
1c530 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
1c540 79 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  y calling sqlite
1c550 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1c560 77 69 64 28 44 29 20 74 6f 20 52 20 0a 2a 2a 20  wid(D) to R .** 
1c570 77 69 74 68 6f 75 74 20 69 6e 73 65 72 74 69 6e  without insertin
1c580 67 20 61 20 72 6f 77 20 69 6e 74 6f 20 74 68 65  g a row into the
1c590 20 64 61 74 61 62 61 73 65 2e 0a 2a 2f 0a 53 51   database..*/.SQ
1c5a0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
1c5b0 6c 69 74 65 33 5f 73 65 74 5f 6c 61 73 74 5f 69  lite3_set_last_i
1c5c0 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
1c5d0 74 65 33 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  te3*,sqlite3_int
1c5e0 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  64);../*.** CAPI
1c5f0 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
1c600 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
1c610 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f  odified.** METHO
1c620 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1c630 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1c640 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
1c650 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66  er of rows modif
1c660 69 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ied, inserted or
1c670 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74  .** deleted by t
1c680 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
1c690 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52   completed INSER
1c6a0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
1c6b0 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
1c6c0 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
1c6d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63   connection spec
1c6e0 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c  ified by the onl
1c6f0 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  y parameter..** 
1c700 5e 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f  ^Executing any o
1c710 74 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c  ther type of SQL
1c720 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
1c730 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76  not modify the v
1c740 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
1c750 20 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f   by this functio
1c760 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63  n..**.** ^Only c
1c770 68 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65  hanges made dire
1c780 63 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45  ctly by the INSE
1c790 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45  RT, UPDATE or DE
1c7a0 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61  LETE statement a
1c7b0 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64  re.** considered
1c7c0 20 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61   - auxiliary cha
1c7d0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b  nges caused by [
1c7e0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
1c7f0 20 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20   triggers], .** 
1c800 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
1c810 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43  ions] or [REPLAC
1c820 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
1c830 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74  solution are not
1c840 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a   counted..** .**
1c850 20 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69   Changes to a vi
1c860 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  ew that are inte
1c870 72 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b  rcepted by .** [
1c880 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1c890 65 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20  er | INSTEAD OF 
1c8a0 74 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f  triggers] are no
1c8b0 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20  t counted. ^The 
1c8c0 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e  value .** return
1c8d0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
1c8e0 61 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74  anges() immediat
1c8f0 65 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53  ely after an INS
1c900 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a  ERT, UPDATE or .
1c910 2a 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d  ** DELETE statem
1c920 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65  ent run on a vie
1c930 77 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  w is always zero
1c940 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d  . Only changes m
1c950 61 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20  ade to real .** 
1c960 74 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74  tables are count
1c970 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73  ed..**.** Things
1c980 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69   are more compli
1c990 63 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c  cated if the sql
1c9a0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66  ite3_changes() f
1c9b0 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78  unction is.** ex
1c9c0 65 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74  ecuted while a t
1c9d0 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69  rigger program i
1c9e0 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20  s running. This 
1c9f0 6d 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68  may happen if th
1ca00 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65  e.** program use
1ca10 73 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  s the [changes()
1ca20 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20   SQL function], 
1ca30 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72  or if some other
1ca40 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1ca50 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71  ction invokes sq
1ca60 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1ca70 64 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74  directly. Essent
1ca80 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75  ially:.** .** <u
1ca90 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42  l>.**   <li> ^(B
1caa0 65 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61  efore entering a
1cab0 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
1cac0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1cad0 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  ned by.**       
1cae0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1caf0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73  () function is s
1cb00 61 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20  aved. After the 
1cb10 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
1cb20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66  .**        has f
1cb30 69 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69  inished, the ori
1cb40 67 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72  ginal value is r
1cb50 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a  estored.)^.** .*
1cb60 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69  *   <li> ^(Withi
1cb70 6e 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  n a trigger prog
1cb80 72 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c  ram each INSERT,
1cb90 20 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45   UPDATE and DELE
1cba0 54 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74  TE .**        st
1cbb0 61 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65  atement sets the
1cbc0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1cbd0 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  by sqlite3_chang
1cbe0 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20  es() .**        
1cbf0 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  upon completion 
1cc00 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f  as normal. Of co
1cc10 75 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65  urse, this value
1cc20 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64   will not includ
1cc30 65 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79  e .**        any
1cc40 20 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d   changes perform
1cc50 65 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65  ed by sub-trigge
1cc60 72 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74  rs, as the sqlit
1cc70 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a  e3_changes() .**
1cc80 20 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69          value wi
1cc90 6c 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20  ll be saved and 
1cca0 72 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65  restored after e
1ccb0 61 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20  ach sub-trigger 
1ccc0 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f  has run.)^.** </
1ccd0 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73  ul>.** .** ^This
1cce0 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74   means that if t
1ccf0 68 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c  he changes() SQL
1cd00 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69   function (or si
1cd10 6d 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a  milar) is used.*
1cd20 2a 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49  * by the first I
1cd30 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
1cd40 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
1cd50 74 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67  t within a trigg
1cd60 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72  er, it .** retur
1cd70 6e 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20  ns the value as 
1cd80 73 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c  set when the cal
1cd90 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62  ling statement b
1cda0 65 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a  egan executing..
1cdb0 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65  ** ^If it is use
1cdc0 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  d by the second 
1cdd0 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75  or subsequent su
1cde0 63 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ch statement wit
1cdf0 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a  hin a trigger .*
1ce00 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76  * program, the v
1ce10 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65  alue returned re
1ce20 66 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65  flects the numbe
1ce30 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
1ce40 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72  ed by the .** pr
1ce50 65 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55  evious INSERT, U
1ce60 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20  PDATE or DELETE 
1ce70 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1ce80 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
1ce90 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
1cea0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
1ceb0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
1cec0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1ced0 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1cee0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1cef0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1cf00 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1cf10 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1cf20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1cf30 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1cf40 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1cf50 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1cf60 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1cf70 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
1cf80 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
1cf90 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
1cfa0 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
1cfb0 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
1cfc0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1cfd0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
1cfe0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1cff0 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
1d000 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
1d010 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48  Modified.** METH
1d020 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
1d030 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1d040 20 72 65 74 75 72 6e 73 20 74 68 65 20 74 6f 74   returns the tot
1d050 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  al number of row
1d060 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f 64 69  s inserted, modi
1d070 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c 65 74  fied or.** delet
1d080 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53 45 52  ed by all [INSER
1d090 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  T], [UPDATE] or 
1d0a0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
1d0b0 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a 2a 2a  nts completed.**
1d0c0 20 73 69 6e 63 65 20 74 68 65 20 64 61 74 61 62   since the datab
1d0d0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
1d0e0 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63 6c 75  as opened, inclu
1d0f0 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65 63 75  ding those execu
1d100 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f  ted as.** part o
1d110 66 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  f trigger progra
1d120 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67 20 61  ms. ^Executing a
1d130 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66  ny other type of
1d140 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
1d150 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66 65 63  * does not affec
1d160 74 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  t the value retu
1d170 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1d180 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 2e  total_changes().
1d190 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  .** .** ^Changes
1d1a0 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
1d1b0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
1d1c0 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63 6c 75  tions] are inclu
1d1d0 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 63 6f  ded in the.** co
1d1e0 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65 20 6d  unt, but those m
1d1f0 61 64 65 20 61 73 20 70 61 72 74 20 6f 66 20 52  ade as part of R
1d200 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61 69 6e  EPLACE constrain
1d210 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65  t resolution are
1d220 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e 67 65  .** not. ^Change
1d230 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
1d240 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
1d250 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46 20 74   by INSTEAD OF t
1d260 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72 65 20  riggers .** are 
1d270 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
1d280 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
1d290 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
1d2a0 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20  s()] interface, 
1d2b0 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68  the.** [count_ch
1d2c0 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61  anges pragma], a
1d2d0 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68  nd the [total_ch
1d2e0 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
1d2f0 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
1d300 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1d310 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
1d320 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
1d330 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
1d340 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
1d350 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1d360 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
1d370 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  en the value.** 
1d380 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72  returned is unpr
1d390 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
1d3a0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
1d3b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1d3c0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1d3d0 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
1d3e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d3f0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
1d400 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
1d410 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1d420 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1d430 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
1d440 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
1d450 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
1d460 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
1d470 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
1d480 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
1d490 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
1d4a0 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
1d4b0 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
1d4c0 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
1d4d0 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
1d4e0 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
1d4f0 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
1d500 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
1d510 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
1d520 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
1d530 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
1d540 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
1d550 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1d560 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
1d570 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
1d580 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
1d590 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
1d5a0 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
1d5b0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1d5c0 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
1d5d0 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
1d5e0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
1d5f0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1d600 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
1d610 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
1d620 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
1d630 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
1d640 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
1d650 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
1d660 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
1d670 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
1d680 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
1d690 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
1d6a0 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
1d6b0 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
1d6c0 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
1d6d0 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
1d6e0 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
1d6f0 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
1d700 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
1d710 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
1d720 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
1d730 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
1d740 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
1d750 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
1d760 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
1d770 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
1d780 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
1d790 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
1d7a0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
1d7b0 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
1d7c0 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
1d7d0 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
1d7e0 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
1d7f0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
1d800 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
1d810 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1d820 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1d830 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
1d840 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
1d850 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
1d860 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1d870 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
1d880 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
1d890 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
1d8a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1d8b0 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1d8c0 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
1d8d0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1d8e0 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
1d8f0 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
1d900 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
1d910 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
1d920 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
1d930 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
1d940 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
1d950 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
1d960 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
1d970 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
1d980 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1d990 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1d9a0 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
1d9b0 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
1d9c0 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
1d9d0 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
1d9e0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1d9f0 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
1da00 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
1da10 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
1da20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
1da30 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
1da40 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1da50 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
1da60 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
1da70 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
1da80 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1da90 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1daa0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1dab0 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
1dac0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1dad0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
1dae0 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
1daf0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1db00 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
1db10 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
1db20 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
1db30 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1db40 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
1db50 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
1db60 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
1db70 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
1db80 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
1db90 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
1dba0 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
1dbb0 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
1dbc0 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
1dbd0 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
1dbe0 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
1dbf0 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
1dc00 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
1dc10 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
1dc20 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
1dc30 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1dc40 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
1dc50 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
1dc60 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
1dc70 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
1dc80 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
1dc90 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
1dca0 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
1dcb0 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
1dcc0 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
1dcd0 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
1dce0 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
1dcf0 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
1dd00 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
1dd10 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
1dd20 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
1dd30 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
1dd40 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
1dd50 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
1dd60 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
1dd70 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
1dd80 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
1dd90 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
1dda0 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
1ddb0 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
1ddc0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
1ddd0 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
1dde0 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
1ddf0 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
1de00 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
1de10 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
1de20 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
1de30 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1de40 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
1de50 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
1de60 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
1de70 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
1de80 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
1de90 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
1dea0 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
1deb0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1dec0 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
1ded0 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
1dee0 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
1def0 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
1df00 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
1df10 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
1df20 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
1df30 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
1df40 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
1df50 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
1df60 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
1df70 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
1df80 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
1df90 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
1dfa0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
1dfb0 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
1dfc0 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
1dfd0 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
1dfe0 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
1dff0 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
1e000 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
1e010 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
1e020 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
1e030 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
1e040 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
1e050 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1e060 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
1e070 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
1e080 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
1e090 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
1e0a0 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
1e0b0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
1e0c0 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
1e0d0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
1e0e0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
1e0f0 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
1e100 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
1e110 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
1e120 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
1e130 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51  yte order..*/.SQ
1e140 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1e150 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
1e160 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
1e170 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1e180 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1e190 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
1e1a0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
1e1b0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
1e1c0 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
1e1d0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
1e1e0 72 72 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  rrors.** KEYWORD
1e1f0 53 3a 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72  S: {busy-handler
1e200 20 63 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79   callback} {busy
1e210 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54   handler}.** MET
1e220 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1e230 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e240 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58  busy_handler(D,X
1e250 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73  ,P) routine sets
1e260 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1e270 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d  tion X.** that m
1e280 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20  ight be invoked 
1e290 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20  with argument P 
1e2a0 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61  whenever.** an a
1e2b0 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
1e2c0 6f 20 61 63 63 65 73 73 20 61 20 64 61 74 61 62  o access a datab
1e2d0 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69  ase table associ
1e2e0 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61  ated with.** [da
1e2f0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e300 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65  n] D when anothe
1e310 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
1e320 72 6f 63 65 73 73 20 68 61 73 20 74 68 65 20 74  rocess has the t
1e330 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20  able locked..** 
1e340 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79  The sqlite3_busy
1e350 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72  _handler() inter
1e360 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
1e370 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71  implement.** [sq
1e380 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1e390 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d  ut()] and [PRAGM
1e3a0 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e  A busy_timeout].
1e3b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
1e3c0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1e3d0 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
1e3e0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72  TE_BUSY].** is r
1e3f0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
1e400 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
1e410 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
1e420 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1e430 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
1e440 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
1e450 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
1e460 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
1e470 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
1e480 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
1e490 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
1e4a0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
1e4b0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
1e4c0 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
1e4d0 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
1e4e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1e4f0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1e500 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
1e510 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
1e520 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1e530 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
1e540 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
1e550 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
1e560 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
1e570 65 65 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76  een invoked prev
1e580 69 6f 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73  iously for the s
1e590 61 6d 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e  ame locking even
1e5a0 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62  t.  ^If the.** b
1e5b0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  usy callback ret
1e5c0 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20  urns 0, then no 
1e5d0 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d  additional attem
1e5e0 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a  pts are made to.
1e5f0 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61  ** access the da
1e600 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49  tabase and [SQLI
1e610 54 45 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75  TE_BUSY] is retu
1e620 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61  rned.** to the a
1e630 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  pplication..** ^
1e640 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
1e650 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
1e660 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
1e670 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
1e680 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  e to access the 
1e690 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65  database and the
1e6a0 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
1e6b0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
1e6c0 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
1e6d0 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
1e6e0 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
1e6f0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
1e700 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
1e710 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
1e720 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
1e730 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
1e740 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
1e750 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
1e760 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
1e770 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
1e780 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
1e790 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
1e7a0 2a 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ** to the applic
1e7b0 61 74 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66  ation instead of
1e7c0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a   invoking the .*
1e7d0 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  * busy handler..
1e7e0 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
1e7f0 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
1e800 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1e810 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
1e820 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
1e830 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
1e840 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
1e850 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
1e860 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
1e870 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
1e880 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
1e890 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
1e8a0 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
1e8b0 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
1e8c0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
1e8d0 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
1e8e0 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1e8f0 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
1e900 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
1e910 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
1e920 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
1e930 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1e940 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
1e950 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
1e960 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
1e970 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
1e980 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
1e990 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
1e9a0 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
1e9b0 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
1e9c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
1e9d0 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
1e9e0 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
1e9f0 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
1ea00 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
1ea10 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
1ea20 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
1ea30 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
1ea40 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1ea50 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
1ea60 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1ea70 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1ea80 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  NULL..**.** ^(Th
1ea90 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ere can only be 
1eaa0 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61  a single busy ha
1eab0 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f  ndler defined fo
1eac0 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  r each.** [datab
1ead0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
1eae0 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20    Setting a new 
1eaf0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65  busy handler cle
1eb00 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69  ars any.** previ
1eb10 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65  ously set handle
1eb20 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74  r.)^  ^Note that
1eb30 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
1eb40 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
1eb50 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69  ].** or evaluati
1eb60 6e 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f  ng [PRAGMA busy_
1eb70 74 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20  timeout=N] will 
1eb80 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75  change the.** bu
1eb90 73 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74  sy handler and t
1eba0 68 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72  hus clear any pr
1ebb0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73  eviously set bus
1ebc0 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a  y handler..**.**
1ebd0 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   The busy callba
1ebe0 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61  ck should not ta
1ebf0 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77  ke any actions w
1ec00 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a  hich modify the.
1ec10 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1ec20 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1ec30 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
1ec40 64 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20  dler.  In other 
1ec50 77 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75  words,.** the bu
1ec60 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f  sy handler is no
1ec70 74 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e  t reentrant.  An
1ec80 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
1ec90 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
1eca0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
1ecb0 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
1ecc0 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
1ecd0 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
1ece0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1ecf0 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
1ed00 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
1ed10 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1ed20 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ndler..*/.SQLITE
1ed30 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1ed40 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
1ed50 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29 28 76 6f  lite3*,int(*)(vo
1ed60 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64 2a 29 3b  id*,int),void*);
1ed70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ed80 3a 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d  : Set A Busy Tim
1ed90 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eout.** METHOD: 
1eda0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
1edb0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
1edc0 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
1edd0 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
1ede0 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
1edf0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
1ee00 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
1ee10 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
1ee20 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
1ee30 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
1ee40 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
1ee50 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
1ee60 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1ee70 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1ee80 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
1ee90 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
1eea0 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
1eeb0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1eec0 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
1eed0 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
1eee0 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
1eef0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
1ef00 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
1ef10 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
1ef20 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68  *.** ^Calling th
1ef30 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1ef40 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
1ef50 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
1ef60 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
1ef70 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
1ef80 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dlers..**.** ^(T
1ef90 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1efa0 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1efb0 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
1efc0 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1efd0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1efe0 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f   at any given mo
1eff0 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65  ment.  If anothe
1f000 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a  r busy handler.*
1f010 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28  * was defined  (
1f020 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62  using [sqlite3_b
1f030 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20  usy_handler()]) 
1f040 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
1f050 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
1f060 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73  , that other bus
1f070 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65  y handler is cle
1f080 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65  ared.)^.**.** Se
1f090 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41  e also:  [PRAGMA
1f0a0 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a   busy_timeout].*
1f0b0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1f0c0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
1f0d0 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
1f0e0 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
1f0f0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
1f100 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
1f110 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
1f120 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  es.** METHOD: sq
1f130 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 69 73  lite3.**.** This
1f140 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
1f150 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
1f160 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
1f170 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1f180 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
1f190 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
1f1a0 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
1f1b0 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
1f1c0 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
1f1d0 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
1f1e0 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
1f1f0 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
1f200 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
1f210 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
1f220 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
1f230 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
1f240 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
1f250 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
1f260 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
1f270 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
1f280 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
1f290 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
1f2a0 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
1f2b0 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
1f2c0 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
1f2d0 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
1f2e0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
1f2f0 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
1f300 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
1f310 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
1f320 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
1f330 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
1f340 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
1f350 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
1f360 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1f370 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
1f380 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
1f390 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1f3a0 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
1f3b0 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
1f3c0 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
1f3d0 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
1f3e0 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
1f3f0 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
1f400 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1f410 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
1f420 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
1f430 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
1f440 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
1f450 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
1f460 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
1f470 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
1f480 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
1f490 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
1f4a0 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
1f4b0 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
1f4c0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1f4d0 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
1f4e0 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
1f4f0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1f500 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
1f510 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1f520 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
1f530 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
1f540 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
1f550 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
1f560 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
1f570 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1f580 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
1f590 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
1f5a0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1f5b0 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
1f5c0 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
1f5d0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1f5e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
1f5f0 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
1f600 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
1f610 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
1f620 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
1f630 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1f640 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1f650 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1f660 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
1f670 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
1f680 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1f690 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
1f6a0 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
1f6b0 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
1f6c0 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
1f6d0 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
1f6e0 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
1f6f0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1f700 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
1f710 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
1f720 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
1f730 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
1f740 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
1f750 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
1f760 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
1f770 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
1f780 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
1f790 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
1f7a0 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
1f7b0 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
1f7c0 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
1f7d0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1f7e0 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1f7f0 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
1f800 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1f810 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
1f820 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1f830 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
1f840 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
1f850 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1f860 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
1f870 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1f880 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
1f890 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1f8a0 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
1f8b0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1f8c0 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
1f8d0 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
1f8e0 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
1f8f0 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
1f900 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1f910 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f920 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
1f930 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
1f940 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
1f950 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
1f960 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
1f970 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
1f980 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1f990 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
1f9a0 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
1f9b0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
1f9c0 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
1f9d0 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
1f9e0 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
1f9f0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
1fa00 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
1fa10 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
1fa20 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
1fa30 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
1fa40 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
1fa50 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
1fa60 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
1fa70 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
1fa80 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
1fa90 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
1faa0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
1fab0 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
1fac0 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
1fad0 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
1fae0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1faf0 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
1fb00 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1fb10 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
1fb20 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
1fb30 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
1fb40 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1fb50 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
1fb60 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
1fb70 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
1fb80 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
1fb90 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
1fba0 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
1fbb0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1fbc0 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
1fbd0 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
1fbe0 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
1fbf0 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
1fc00 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
1fc10 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1fc20 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
1fc30 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
1fc40 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
1fc50 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
1fc60 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
1fc70 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
1fc80 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
1fc90 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
1fca0 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
1fcb0 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
1fcc0 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
1fcd0 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
1fce0 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
1fcf0 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
1fd00 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
1fd10 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
1fd20 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
1fd30 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
1fd40 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1fd50 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1fd60 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53  _errmsg()]..*/.S
1fd70 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1fd80 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1fd90 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1fda0 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
1fdb0 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
1fdc0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1fdd0 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
1fde0 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
1fdf0 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
1fe00 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1fe10 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1fe20 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1fe30 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1fe40 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1fe50 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1fe60 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1fe70 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1fe80 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1fe90 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1fea0 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1feb0 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1fec0 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1fed0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1fee0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1fef0 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
1ff00 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
1ff10 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
1ff20 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
1ff30 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
1ff40 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1ff50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1ff60 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
1ff70 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
1ff80 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
1ff90 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
1ffa0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1ffb0 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ary..** These ro
1ffc0 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74 61 6e  utines understan
1ffd0 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 63 6f  d most of the co
1ffe0 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61 74 74  mmon K&R formatt
1fff0 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a 2a 20  ing options,.** 
20000 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69 74 69  plus some additi
20010 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64 61 72  onal non-standar
20020 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74 61 69  d formats, detai
20030 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20 4e 6f  led below..** No
20040 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f 66 20  te that some of 
20050 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75 72 65  the more obscure
20060 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
20070 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e 74 0a  ons from recent.
20080 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73 74 61  ** C-library sta
20090 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69 74 74  ndards are omitt
200a0 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69 6d 70  ed from this imp
200b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 0a  lementation..**.
200c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
200d0 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
200e0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
200f0 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
20100 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
20110 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
20120 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
20130 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
20140 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
20150 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
20160 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
20170 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
20180 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
20190 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
201a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
201b0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
201c0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
201d0 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
201e0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
201f0 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
20200 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
20210 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
20220 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
20230 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
20240 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
20250 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
20260 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
20270 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
20280 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
20290 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
202a0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
202b0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
202c0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
202d0 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
202e0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
202f0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
20300 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
20310 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
20320 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
20330 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
20340 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
20350 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
20360 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
20370 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
20380 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
20390 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
203a0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
203b0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
203c0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
203d0 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
203e0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
203f0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
20400 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
20410 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
20420 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
20430 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
20440 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
20450 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
20460 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
20470 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
20480 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
20490 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
204a0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
204b0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
204c0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
204d0 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
204e0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
204f0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
20500 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
20510 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
20520 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
20530 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
20540 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
20550 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
20560 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
20570 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
20580 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
20590 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
205a0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
205b0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
205c0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
205d0 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
205e0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
205f0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
20600 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
20610 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
20620 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
20630 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
20640 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
20650 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
20660 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
20670 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
20680 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
20690 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
206a0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
206b0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
206c0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
206d0 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
206e0 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
206f0 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
20700 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
20710 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
20720 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
20730 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
20740 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
20750 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
20760 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 22 25  e "%q", "%Q", "%
20770 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  w" and "%z" opti
20780 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
20790 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
207a0 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
207b0 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
207c0 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
207d0 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
207e0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
207f0 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
20800 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
20810 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
20820 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
20830 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
20840 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
20850 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
20860 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
20870 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
20880 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
20890 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
208a0 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
208b0 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
208c0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
208d0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
208e0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
208f0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
20900 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
20910 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
20920 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
20930 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
20940 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
20950 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
20960 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
20970 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
20980 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
20990 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
209a0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
209b0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
209c0 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
209d0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
209e0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
209f0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
20a00 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
20a10 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
20a20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
20a30 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
20a40 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
20a50 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
20a60 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
20a70 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
20a80 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
20a90 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
20aa0 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
20ab0 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
20ac0 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
20ad0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
20ae0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
20af0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
20b00 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
20b10 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
20b20 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
20b30 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
20b40 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
20b50 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
20b60 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
20b70 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
20b80 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
20b90 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
20ba0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
20bb0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
20bc0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
20bd0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
20be0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
20bf0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
20c00 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
20c10 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
20c20 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
20c30 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
20c40 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
20c50 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
20c60 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
20c70 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
20c80 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
20c90 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
20ca0 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
20cb0 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
20cc0 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
20cd0 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
20ce0 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
20cf0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
20d00 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
20d10 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
20d20 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
20d30 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
20d40 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
20d50 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
20d60 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
20d70 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
20d80 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
20d90 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
20da0 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
20db0 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
20dc0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
20dd0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
20de0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
20df0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
20e00 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
20e10 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
20e20 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
20e30 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
20e40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
20e50 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
20e60 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
20e70 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
20e80 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
20e90 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
20ea0 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
20eb0 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
20ec0 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
20ed0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
20ee0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
20ef0 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72 6d 61  ^(The "%w" forma
20f00 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20  tting option is 
20f10 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65 70 74  like "%q" except
20f20 20 74 68 61 74 20 69 74 20 65 78 70 65 63 74 73   that it expects
20f30 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74 61 69   to.** be contai
20f40 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75 62 6c  ned within doubl
20f50 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65 61 64  e-quotes instead
20f60 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f 74 65   of single quote
20f70 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65 73 63  s, and it.** esc
20f80 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c 65 2d  apes the double-
20f90 71 75 6f 74 65 20 63 68 61 72 61 63 74 65 72 20  quote character 
20fa0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 73  instead of the s
20fb0 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a 20 63  ingle-quote.** c
20fc0 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54 68 65  haracter.)^  The
20fd0 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%w" formatting
20fe0 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74 65 6e   option is inten
20ff0 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79 20 69  ded for safely i
21000 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61 62 6c  nserting.** tabl
21010 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  e and column nam
21020 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73 74 72  es into a constr
21030 75 63 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  ucted SQL statem
21040 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ent..**.** ^(The
21050 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
21060 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
21070 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
21080 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
21090 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
210a0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
210b0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
210c0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
210d0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
210e0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
210f0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
21100 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ng.)^.*/.SQLITE_
21110 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
21120 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
21130 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49  char*,...);.SQLI
21140 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
21150 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
21160 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
21170 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  st);.SQLITE_API 
21180 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
21190 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
211a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
211b0 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .);.SQLITE_API c
211c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e  har *sqlite3_vsn
211d0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
211e0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  ,const char*, va
211f0 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _list);../*.** C
21200 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
21210 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
21220 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
21230 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
21240 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
21250 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
21260 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
21270 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
21280 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
21290 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
212a0 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
212b0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
212c0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
212d0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
212e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
212f0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
21300 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
21310 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
21320 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
21330 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
21340 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
21350 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
21360 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
21370 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
21380 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
21390 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
213a0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
213b0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
213c0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
213d0 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
213e0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
213f0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
21400 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
21410 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
21420 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
21430 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
21440 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
21450 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
21460 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
21470 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
21480 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
21490 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
214a0 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f  3_malloc64(N) ro
214b0 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74  utine works just
214c0 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33   like.** sqlite3
214d0 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70  _malloc(N) excep
214e0 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75  t that N is an u
214f0 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69  nsigned 64-bit i
21500 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
21510 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32  * of a signed 32
21520 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  -bit integer..**
21530 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
21540 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
21550 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
21560 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
21570 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
21580 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
21590 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
215a0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
215b0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
215c0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
215d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
215e0 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
215f0 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
21600 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
21610 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
21620 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
21630 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
21640 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
21650 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
21660 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
21670 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
21680 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
21690 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
216a0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
216b0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
216c0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
216d0 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
216e0 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
216f0 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
21700 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
21710 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
21720 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
21730 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
21740 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
21750 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
21760 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
21770 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
21780 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
21790 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
217a0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
217b0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
217c0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  lloc()..**.** ^T
217d0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
217e0 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  oc(X,N) interfac
217f0 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
21800 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
21810 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
21820 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61  n X to be at lea
21830 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  st N bytes..** ^
21840 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74  If the X paramet
21850 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
21860 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73  alloc(X,N).** is
21870 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
21880 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
21890 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
218a0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
218b0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a  ite3_malloc(N)..
218c0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72  ** ^If the N par
218d0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
218e0 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
218f0 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
21900 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
21910 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
21920 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
21930 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
21940 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73  3_free(X)..** ^s
21950 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
21960 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ,N) returns a po
21970 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
21980 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
21990 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
219a0 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
219b0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
219c0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76  ent memory is av
219d0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
219e0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
219f0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
21a00 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
21a10 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
21a20 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
21a30 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
21a40 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
21a50 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
21a60 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
21a70 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
21a80 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
21a90 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
21aa0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
21ab0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
21ac0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
21ad0 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c  d N is positive,
21ae0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69   then the.** pri
21af0 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
21b00 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
21b10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
21b20 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e  ealloc64(X,N) in
21b30 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74  terfaces works t
21b40 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
21b50 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
21b60 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
21b70 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73   is a 64-bit uns
21b80 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e  igned integer in
21b90 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32  stead.** of a 32
21ba0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
21bb0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58  ger..**.** ^If X
21bc0 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   is a memory all
21bd0 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73  ocation previous
21be0 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
21bf0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
21c00 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ),.** sqlite3_ma
21c10 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65  lloc64(), sqlite
21c20 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20  3_realloc(), or 
21c30 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
21c40 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  4(), then.** sql
21c50 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
21c60 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
21c70 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c  f that memory al
21c80 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65  location in byte
21c90 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  s..** ^The value
21ca0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
21cb0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69  ite3_msize(X) mi
21cc0 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68  ght be larger th
21cd0 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  an the number.**
21ce0 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73   of bytes reques
21cf0 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61  ted when X was a
21d00 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58  llocated.  ^If X
21d10 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
21d20 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  er then.** sqlit
21d30 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
21d40 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20  rns zero.  If X 
21d50 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68  points to someth
21d60 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a  ing that is not.
21d70 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  ** the beginning
21d80 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
21d90 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20  ation, or if it 
21da0 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d  points to a form
21db0 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65  erly.** valid me
21dc0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
21dd0 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65  that has now bee
21de0 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68  n freed, then th
21df0 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
21e00 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
21e10 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  ) is undefined a
21e20 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d  nd possibly harm
21e30 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ful..**.** ^The 
21e40 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
21e50 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
21e60 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61  c(), sqlite3_rea
21e70 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
21e80 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61  e3_malloc64(), a
21e90 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
21ea0 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77  oc64().** is alw
21eb0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
21ec0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
21ed0 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
21ee0 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
21ef0 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
21f00 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
21f10 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
21f20 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
21f30 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
21f40 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
21f50 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
21f60 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
21f70 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
21f80 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
21f90 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
21fa0 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
21fb0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
21fc0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
21fd0 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
21fe0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
21ff0 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
22000 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
22010 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
22020 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
22030 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
22040 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
22050 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
22060 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
22070 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77  7.10, the Window
22080 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
22090 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  ayer called.** t
220a0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
220b0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
220c0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
220d0 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
220e0 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
220f0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
22100 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
22110 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
22120 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
22130 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
22140 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
22150 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
22160 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
22170 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72  ation errors wer
22180 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
22190 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70  ** they were rep
221a0 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
221b0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
221c0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
221d0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
221e0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
221f0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
22200 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
22210 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
22220 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
22230 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
22240 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
22250 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
22260 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
22270 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
22280 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
22290 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
222a0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
222b0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
222c0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
222d0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
222e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
222f0 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
22300 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
22310 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
22320 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
22330 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
22340 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
22350 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
22360 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
22370 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
22380 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c  oid *sqlite3_mal
22390 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45  loc(int);.SQLITE
223a0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
223b0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
223c0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c  te3_uint64);.SQL
223d0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
223e0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
223f0 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  id*, int);.SQLIT
22400 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
22410 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 76 6f  te3_realloc64(vo
22420 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  id*, sqlite3_uin
22430 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
22440 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72   void sqlite3_fr
22450 65 65 28 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ee(void*);.SQLIT
22460 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 75 69  E_API sqlite3_ui
22470 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 73 69  nt64 sqlite3_msi
22480 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ze(void*);../*.*
22490 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
224a0 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
224b0 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
224c0 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
224d0 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
224e0 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
224f0 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
22500 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
22510 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
22520 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
22530 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
22540 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
22550 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
22560 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
22570 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
22580 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
22590 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
225a0 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
225b0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
225c0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
225d0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
225e0 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
225f0 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
22600 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
22610 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
22620 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
22630 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
22640 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
22650 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
22660 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
22670 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
22680 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
22690 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
226a0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
226b0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
226c0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
226d0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
226e0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
226f0 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
22700 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
22710 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
22720 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
22730 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
22740 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
22750 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
22760 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
22770 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
22780 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
22790 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
227a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
227b0 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
227c0 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
227d0 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
227e0 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
227f0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
22800 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
22810 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
22820 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
22830 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
22840 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
22850 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
22860 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
22870 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
22880 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
22890 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
228a0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
228b0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
228c0 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
228d0 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
228e0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
228f0 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  sed(void);.SQLIT
22900 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
22910 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
22920 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
22930 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
22940 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
22950 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
22960 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
22970 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
22980 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
22990 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
229a0 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
229b0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
229c0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
229d0 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
229e0 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
229f0 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
22a00 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
22a10 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
22a20 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
22a30 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
22a40 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
22a50 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
22a60 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
22a70 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
22a80 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
22a90 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
22aa0 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
22ab0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
22ac0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
22ad0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
22ae0 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
22af0 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
22b00 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
22b10 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
22b20 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
22b30 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65 74 65   ^The P paramete
22b40 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20  r can be a NULL 
22b50 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
22b60 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  If this routine 
22b70 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65  has not been pre
22b80 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f  viously called o
22b90 72 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  r if the previou
22ba0 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20  s.** call had N 
22bb0 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72  less than one or
22bc0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
22bd0 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20  for P, then the 
22be0 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65  PRNG is.** seede
22bf0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
22c00 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ss obtained from
22c10 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
22c20 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68   method of.** th
22c30 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
22c40 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
22c50 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
22c60 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
22c70 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
22c80 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61  N of 1 or more a
22c90 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c  nd a.** non-NULL
22ca0 20 50 20 74 68 65 6e 20 74 68 65 20 70 73 65 75   P then the pseu
22cb0 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
22cc0 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
22cd0 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
22ce0 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
22cf0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
22d00 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
22d10 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c  * method..*/.SQL
22d20 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
22d30 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
22d40 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
22d50 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22d60 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
22d70 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
22d80 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
22d90 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 4b 45 59  : sqlite3.** KEY
22da0 57 4f 52 44 53 3a 20 7b 61 75 74 68 6f 72 69 7a  WORDS: {authoriz
22db0 65 72 20 63 61 6c 6c 62 61 63 6b 7d 0a 2a 2a 0a  er callback}.**.
22dc0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
22dd0 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
22de0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
22df0 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
22e00 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
22e10 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
22e20 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
22e30 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
22e40 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
22e50 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
22e60 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
22e70 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
22e80 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
22e90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22ea0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
22eb0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
22ec0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
22ed0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
22ee0 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
22ef0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
22f00 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
22f10 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
22f20 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
22f30 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
22f40 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
22f50 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
22f60 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
22f70 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
22f80 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
22f90 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
22fa0 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
22fb0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
22fc0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
22fd0 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
22fe0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
22ff0 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
23000 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
23010 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
23020 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
23030 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
23040 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
23050 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
23060 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
23070 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
23080 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
23090 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
230a0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
230b0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
230c0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
230d0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
230e0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
230f0 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
23100 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
23110 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
23120 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
23130 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
23140 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
23150 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
23160 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
23170 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
23180 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
23190 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
231a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
231b0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
231c0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
231d0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
231e0 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
231f0 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
23200 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
23210 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
23220 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
23230 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
23240 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
23250 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
23260 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
23270 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
23280 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
23290 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
232a0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
232b0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
232c0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
232d0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
232e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
232f0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
23300 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
23310 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
23320 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
23330 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
23340 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
23350 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
23360 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
23370 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
23380 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
23390 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
233a0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
233b0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
233c0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
233d0 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
233e0 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
233f0 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
23400 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
23410 6c 62 61 63 6b 20 61 72 65 20 65 69 74 68 65 72  lback are either
23420 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6f   NULL pointers o
23430 72 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  r zero-terminate
23440 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 74 68 61  d strings.** tha
23450 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69  t contain additi
23460 6f 6e 61 6c 20 64 65 74 61 69 6c 73 20 61 62 6f  onal details abo
23470 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
23480 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
23490 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
234a0 6d 75 73 74 20 61 6c 77 61 79 73 20 62 65 20 70  must always be p
234b0 72 65 70 61 72 65 64 20 74 6f 20 65 6e 63 6f 75  repared to encou
234c0 6e 74 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  nter a NULL poin
234d0 74 65 72 20 69 6e 20 61 6e 79 0a 2a 2a 20 6f 66  ter in any.** of
234e0 20 74 68 65 20 74 68 69 72 64 20 74 68 72 6f 75   the third throu
234f0 67 68 20 74 68 65 20 73 69 78 74 68 20 70 61 72  gh the sixth par
23500 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 61  ameters of the a
23510 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 63 61 6c  uthorization cal
23520 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  lback..**.** ^If
23530 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
23540 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
23550 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
23560 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
23570 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
23580 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
23590 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
235a0 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
235b0 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
235c0 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
235d0 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
235e0 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
235f0 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
23600 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
23610 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
23620 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
23630 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
23640 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
23650 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
23660 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
23670 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
23680 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
23690 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
236a0 65 2e 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 74 61  e..** ^When a ta
236b0 62 6c 65 20 69 73 20 72 65 66 65 72 65 6e 63 65  ble is reference
236c0 64 20 62 79 20 61 20 5b 53 45 4c 45 43 54 5d 20  d by a [SELECT] 
236d0 62 75 74 20 6e 6f 20 63 6f 6c 75 6d 6e 20 76 61  but no column va
236e0 6c 75 65 73 20 61 72 65 0a 2a 2a 20 65 78 74 72  lues are.** extr
236f0 61 63 74 65 64 20 66 72 6f 6d 20 74 68 61 74 20  acted from that 
23700 74 61 62 6c 65 20 28 66 6f 72 20 65 78 61 6d 70  table (for examp
23710 6c 65 20 69 6e 20 61 20 71 75 65 72 79 20 6c 69  le in a query li
23720 6b 65 0a 2a 2a 20 22 53 45 4c 45 43 54 20 63 6f  ke.** "SELECT co
23730 75 6e 74 28 2a 29 20 46 52 4f 4d 20 74 61 62 22  unt(*) FROM tab"
23740 29 20 74 68 65 6e 20 74 68 65 20 5b 53 51 4c 49  ) then the [SQLI
23750 54 45 5f 52 45 41 44 5d 20 61 75 74 68 6f 72 69  TE_READ] authori
23760 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  zer callback.** 
23770 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 63 65 20  is invoked once 
23780 66 6f 72 20 74 68 61 74 20 74 61 62 6c 65 20 77  for that table w
23790 69 74 68 20 61 20 63 6f 6c 75 6d 6e 20 6e 61 6d  ith a column nam
237a0 65 20 74 68 61 74 20 69 73 20 61 6e 20 65 6d 70  e that is an emp
237b0 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  ty string..** ^I
237c0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
237d0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c  e is [SQLITE_DEL
237e0 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c  ETE] and the cal
237f0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
23800 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
23810 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54   then the [DELET
23820 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f  E] operation pro
23830 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a  ceeds but the.**
23840 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
23850 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61  ization] is disa
23860 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77  bled and all row
23870 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e  s are deleted in
23880 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a  dividually..**.*
23890 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20  * An authorizer 
238a0 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71  is used when [sq
238b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
238c0 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51  preparing].** SQ
238d0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f  L statements fro
238e0 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  m an untrusted s
238f0 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65  ource, to ensure
23900 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74   that the SQL st
23910 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e  atements.** do n
23920 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73  ot try to access
23930 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e   data they are n
23940 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65  ot allowed to se
23950 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20  e, or that they 
23960 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f  do not.** try to
23970 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f   execute malicio
23980 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  us statements th
23990 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61  at damage the da
239a0 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20  tabase.  For.** 
239b0 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
239c0 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f  ication may allo
239d0 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65  w a user to ente
239e0 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53  r arbitrary.** S
239f0 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65  QL queries for e
23a00 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64  valuation by a d
23a10 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68  atabase.  But th
23a20 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f  e application do
23a30 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74  es.** not want t
23a40 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62  he user to be ab
23a50 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74  le to make arbit
23a60 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20  rary changes to 
23a70 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  the.** database.
23a80 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20    An authorizer 
23a90 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75  could then be pu
23aa0 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65  t in place while
23ab0 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74   the.** user-ent
23ac0 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e  ered SQL is bein
23ad0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
23ae0 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74  re | prepared] t
23af0 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73  hat.** disallows
23b00 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65   everything exce
23b10 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  pt [SELECT] stat
23b20 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70  ements..**.** Ap
23b30 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
23b40 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20  need to process 
23b50 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74  SQL from untrust
23b60 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69  ed sources.** mi
23b70 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65  ght also conside
23b80 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75  r lowering resou
23b90 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67  rce limits using
23ba0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
23bb0 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69  )].** and limiti
23bc0 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65  ng database size
23bd0 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f   using the [max_
23be0 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41  page_count] [PRA
23bf0 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74  GMA].** in addit
23c00 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20  ion to using an 
23c10 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a  authorizer..**.*
23c20 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  * ^(Only a singl
23c30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e  e authorizer can
23c40 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20   be in place on 
23c50 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
23c60 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69  ction.** at a ti
23c70 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74  me.  Each call t
23c80 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
23c90 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64  thorizer overrid
23ca0 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f  es the.** previo
23cb0 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73  us call.)^  ^Dis
23cc0 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69  able the authori
23cd0 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e  zer by installin
23ce0 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63  g a NULL callbac
23cf0 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  k..** The author
23d00 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64  izer is disabled
23d10 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a   by default..**.
23d20 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
23d30 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
23d40 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
23d50 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
23d60 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
23d70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
23d80 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74   invoked the aut
23d90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
23da0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
23db0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
23dc0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
23dd0 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
23de0 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
23df0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23e00 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
23e10 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
23e20 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
23e30 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ph..**.** ^When 
23e40 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23e50 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74  _v2()] is used t
23e60 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74  o prepare a stat
23e70 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74  ement, the.** st
23e80 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65  atement might be
23e90 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72   re-prepared dur
23ea0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
23eb0 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a  p()] due to a .*
23ec0 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e  * schema change.
23ed0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70    Hence, the app
23ee0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
23ef0 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  ensure that the.
23f00 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f  ** correct autho
23f10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
23f20 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20  emains in place 
23f30 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69  during the [sqli
23f40 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a  te3_step()]..**.
23f50 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68  ** ^Note that th
23f60 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
23f70 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
23f80 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20   only during.** 
23f90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23fa0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
23fb0 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74  nts.  Authorizat
23fc0 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65  ion is not.** pe
23fd0 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73  rformed during s
23fe0 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74  tatement evaluat
23ff0 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f  ion in [sqlite3_
24000 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a  step()], unless.
24010 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20  ** as stated in 
24020 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
24030 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f  agraph, sqlite3_
24040 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a  step() invokes.*
24050 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  * sqlite3_prepar
24060 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70  e_v2() to reprep
24070 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20  are a statement 
24080 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63  after a schema c
24090 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  hange..*/.SQLITE
240a0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
240b0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
240c0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
240d0 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
240e0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
240f0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
24100 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
24110 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
24120 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
24130 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
24140 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
24150 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
24160 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
24170 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
24180 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
24190 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
241a0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
241b0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
241c0 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
241d0 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
241e0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
241f0 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
24200 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
24210 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
24220 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
24230 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
24240 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
24250 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
24260 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
24270 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
24280 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
24290 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
242a0 6f 20 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e  o used as a [con
242b0 66 6c 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e  flict resolution
242c0 20 6d 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e   mode].** return
242d0 65 64 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c  ed from the [sql
242e0 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e  ite3_vtab_on_con
242f0 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61  flict()] interfa
24300 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ce..*/.#define S
24310 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20  QLITE_DENY   1  
24320 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51   /* Abort the SQ
24330 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  L statement with
24340 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65   an error */.#de
24350 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f  fine SQLITE_IGNO
24360 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20  RE 2   /* Don't 
24370 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75  allow access, bu
24380 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65  t don't generate
24390 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a   an error */../*
243a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
243b0 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20  thorizer Action 
243c0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
243d0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
243e0 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72  horizer()] inter
243f0 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61  face registers a
24400 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
24410 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e  on.** that is in
24420 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69  voked to authori
24430 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73  ze certain SQL s
24440 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73  tatement actions
24450 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  .  The.** second
24460 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
24470 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
24480 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68   integer code th
24490 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  at specifies.** 
244a0 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62  what action is b
244b0 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e  eing authorized.
244c0 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20    These are the 
244d0 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63  integer action c
244e0 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  odes that.** the
244f0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
24500 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73  back may be pass
24510 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
24520 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75  action code valu
24530 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20  es signify what 
24540 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f  kind of operatio
24550 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75  n is to be.** au
24560 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33  thorized.  The 3
24570 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d  rd and 4th param
24580 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74  eters to the aut
24590 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61  horization.** ca
245a0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
245b0 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65  will be paramete
245c0 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e  rs or NULL depen
245d0 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66  ding on which of
245e0 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20   these.** codes 
245f0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73  is used as the s
24600 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
24610 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61    ^(The 5th para
24620 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  meter to the.** 
24630 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
24640 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ack is the name 
24650 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
24660 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c  ("main", "temp",
24670 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70  .** etc.) if app
24680 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65  licable.)^  ^The
24690 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   6th parameter t
246a0 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  o the authorizer
246b0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20   callback.** is 
246c0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
246d0 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67  inner-most trigg
246e0 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20  er or view that 
246f0 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
24700 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73  or.** the access
24710 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c   attempt or NULL
24720 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20   if this access 
24730 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63  attempt is direc
24740 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d  tly from.** top-
24750 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a  level SQL code..
24760 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
24770 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
24780 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  *************** 
24790 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3rd ************
247a0 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   4th ***********
247b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
247c0 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20  _CREATE_INDEX   
247d0 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e         1   /* In
247e0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
247f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
24800 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24810 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20  CREATE_TABLE    
24820 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62        2   /* Tab
24830 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
24840 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
24850 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
24860 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58  REATE_TEMP_INDEX
24870 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65       3   /* Inde
24880 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
24890 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
248a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
248b0 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20  EATE_TEMP_TABLE 
248c0 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65      4   /* Table
248d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
248e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
248f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
24900 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ATE_TEMP_TRIGGER
24910 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65     5   /* Trigge
24920 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
24930 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
24940 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
24950 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  TE_TEMP_VIEW    
24960 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    6   /* View Na
24970 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
24980 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
24990 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
249a0 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  E_TRIGGER       
249b0 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   7   /* Trigger 
249c0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
249d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
249e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
249f0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
24a00 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  8   /* View Name
24a10 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
24a20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
24a30 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20  e SQLITE_DELETE 
24a40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39                 9
24a50 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
24a60 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
24a70 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
24a80 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44   SQLITE_DROP_IND
24a90 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20  EX           10 
24aa0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
24ab0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
24ac0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24ad0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c  SQLITE_DROP_TABL
24ae0 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20  E           11  
24af0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
24b00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
24b10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
24b20 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
24b30 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20  INDEX      12   
24b40 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
24b50 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
24b60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
24b70 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
24b80 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f  ABLE      13   /
24b90 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
24ba0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
24bb0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
24bc0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52  ITE_DROP_TEMP_TR
24bd0 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a  IGGER    14   /*
24be0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
24bf0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
24c00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
24c10 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45  TE_DROP_TEMP_VIE
24c20 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20  W       15   /* 
24c30 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
24c40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
24c50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
24c60 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20  E_DROP_TRIGGER  
24c70 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54         16   /* T
24c80 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
24c90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
24ca0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
24cb0 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20  _DROP_VIEW      
24cc0 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69        17   /* Vi
24cd0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
24ce0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
24cf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
24d00 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20  INSERT          
24d10 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62       18   /* Tab
24d20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
24d30 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
24d40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50  #define SQLITE_P
24d50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
24d60 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67      19   /* Prag
24d70 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20  ma Name     1st 
24d80 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23  arg or NULL */.#
24d90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
24da0 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
24db0 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65     20   /* Table
24dc0 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d   Name      Colum
24dd0 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  n Name     */.#d
24de0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c  efine SQLITE_SEL
24df0 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ECT             
24e00 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    21   /* NULL  
24e10 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
24e20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
24e30 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e  fine SQLITE_TRAN
24e40 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  SACTION         
24e50 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   22   /* Operati
24e60 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  on       NULL   
24e70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
24e80 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54  ine SQLITE_UPDAT
24e90 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
24ea0 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  23   /* Table Na
24eb0 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
24ec0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
24ed0 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48  ne SQLITE_ATTACH
24ee0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
24ef0 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20  4   /* Filename 
24f00 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
24f10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
24f20 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20  e SQLITE_DETACH 
24f30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
24f40 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
24f50 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20  ame   NULL      
24f60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
24f70 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41   SQLITE_ALTER_TA
24f80 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20  BLE          26 
24f90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
24fa0 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  me   Table Name 
24fb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
24fc0 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20  SQLITE_REINDEX  
24fd0 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20              27  
24fe0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
24ff0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
25000 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
25010 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20  QLITE_ANALYZE   
25020 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20             28   
25030 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
25040 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
25050 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
25060 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42  LITE_CREATE_VTAB
25070 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f  LE        29   /
25080 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
25090 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
250a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
250b0 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20  ITE_DROP_VTABLE 
250c0 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a           30   /*
250d0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
250e0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
250f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
25100 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20  TE_FUNCTION     
25110 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20          31   /* 
25120 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
25130 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20  Function Name   
25140 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
25150 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20  E_SAVEPOINT     
25160 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f         32   /* O
25170 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53  peration       S
25180 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a  avepoint Name  *
25190 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
251a0 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20  _COPY           
251b0 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f         0   /* No
251c0 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a   longer used */.
251d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
251e0 45 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20  ECURSIVE        
251f0 20 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c      33   /* NULL
25200 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
25210 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a              */..
25220 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25230 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
25240 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
25250 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
25260 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  e3.**.** These r
25270 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 70 72  outines are depr
25280 65 63 61 74 65 64 2e 20 55 73 65 20 74 68 65 20  ecated. Use the 
25290 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
252a0 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  2()] interface.*
252b0 2a 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  * instead of the
252c0 20 72 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69   routines descri
252d0 62 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  bed here..**.** 
252e0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
252f0 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
25300 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
25310 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
25320 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
25330 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
25340 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
25350 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
25360 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
25370 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
25380 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
25390 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
253a0 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
253b0 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
253c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
253d0 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
253e0 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
253f0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
25400 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
25410 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
25420 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
25430 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
25440 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
25450 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
25460 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
25470 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
25480 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
25490 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
254a0 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
254b0 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
254c0 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
254d0 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
254e0 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
254f0 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
25500 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
25510 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
25520 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
25530 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
25540 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
25550 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
25560 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  e option can be 
25570 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a  used to limit.**
25580 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b   the length of [
25590 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d  bound parameter]
255a0 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68   expansion in th
255b0 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69  e output of sqli
255c0 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a  te3_trace()..**.
255d0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
255e0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
255f0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
25600 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
25610 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
25620 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
25630 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
25640 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
25650 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
25660 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
25670 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
25680 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
25690 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
256a0 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
256b0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
256c0 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
256d0 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
256e0 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
256f0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
25700 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
25710 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
25720 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
25730 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
25740 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
25750 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
25760 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
25770 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
25780 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
25790 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
257a0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
257b0 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
257c0 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
257d0 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
257e0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
257f0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
25800 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
25810 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
25820 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
25830 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
25840 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
25850 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
25860 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ite..*/.SQLITE_A
25870 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
25880 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74  ATED void *sqlit
25890 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
258a0 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 54 72 61  *,.   void(*xTra
258b0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
258c0 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
258d0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
258e0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
258f0 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  d *sqlite3_profi
25900 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
25910 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
25920 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
25930 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
25940 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
25950 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
25960 54 72 61 63 65 20 45 76 65 6e 74 20 43 6f 64 65  Trace Event Code
25970 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
25980 51 4c 49 54 45 5f 54 52 41 43 45 0a 2a 2a 0a 2a  QLITE_TRACE.**.*
25990 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
259a0 73 20 69 64 65 6e 74 69 66 79 20 63 6c 61 73 73  s identify class
259b0 65 73 20 6f 66 20 65 76 65 6e 74 73 20 74 68 61  es of events tha
259c0 74 20 63 61 6e 20 62 65 20 6d 6f 6e 69 74 6f 72  t can be monitor
259d0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20  ed.** using the 
259e0 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76  [sqlite3_trace_v
259f0 32 28 29 5d 20 74 72 61 63 69 6e 67 20 6c 6f 67  2()] tracing log
25a00 69 63 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  ic.  The third a
25a10 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73  rgument.** to [s
25a20 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
25a30 29 5d 20 69 73 20 61 6e 20 4f 52 2d 65 64 20 63  )] is an OR-ed c
25a40 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 6f 6e  ombination of on
25a50 65 20 6f 72 20 6d 6f 72 65 20 6f 66 0a 2a 2a 20  e or more of.** 
25a60 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f  the following co
25a70 6e 73 74 61 6e 74 73 2e 20 20 5e 54 68 65 20 66  nstants.  ^The f
25a80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
25a90 20 74 68 65 20 74 72 61 63 65 20 63 61 6c 6c 62   the trace callb
25aa0 61 63 6b 0a 2a 2a 20 69 73 20 6f 6e 65 20 6f 66  ack.** is one of
25ab0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
25ac0 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  onstants..**.** 
25ad0 4e 65 77 20 74 72 61 63 69 6e 67 20 63 6f 6e 73  New tracing cons
25ae0 74 61 6e 74 73 20 6d 61 79 20 62 65 20 61 64 64  tants may be add
25af0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
25b00 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  eases..**.** ^A 
25b10 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b 20 68  trace callback h
25b20 61 73 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74  as four argument
25b30 73 3a 20 78 43 61 6c 6c 62 61 63 6b 28 54 2c 43  s: xCallback(T,C
25b40 2c 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54  ,P,X)..** ^The T
25b50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65   argument is one
25b60 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   of the integer 
25b70 74 79 70 65 20 63 6f 64 65 73 20 61 62 6f 76 65  type codes above
25b80 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61 72 67 75  ..** ^The C argu
25b90 6d 65 6e 74 20 69 73 20 61 20 63 6f 70 79 20 6f  ment is a copy o
25ba0 66 20 74 68 65 20 63 6f 6e 74 65 78 74 20 70 6f  f the context po
25bb0 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 20  inter passed in 
25bc0 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  as the.** fourth
25bd0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
25be0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
25bf0 5d 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20  ]..** The P and 
25c00 58 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20  X arguments are 
25c10 70 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d  pointers whose m
25c20 65 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f  eanings depend o
25c30 6e 20 54 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  n T..**.** <dl>.
25c40 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43  ** [[SQLITE_TRAC
25c50 45 5f 53 54 4d 54 5d 5d 20 3c 64 74 3e 53 51 4c  E_STMT]] <dt>SQL
25c60 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 3c 2f  ITE_TRACE_STMT</
25c70 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
25c80 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54  QLITE_TRACE_STMT
25c90 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
25ca0 6f 6b 65 64 20 77 68 65 6e 20 61 20 70 72 65 70  oked when a prep
25cb0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
25cc0 2a 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 72  * first begins r
25cd0 75 6e 6e 69 6e 67 20 61 6e 64 20 70 6f 73 73 69  unning and possi
25ce0 62 6c 79 20 61 74 20 6f 74 68 65 72 20 74 69 6d  bly at other tim
25cf0 65 73 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  es during the.**
25d00 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68   execution of th
25d10 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
25d20 6d 65 6e 74 2c 20 73 75 63 68 20 61 73 20 61 74  ment, such as at
25d30 20 74 68 65 20 73 74 61 72 74 20 6f 66 20 65 61   the start of ea
25d40 63 68 0a 2a 2a 20 74 72 69 67 67 65 72 20 73 75  ch.** trigger su
25d50 62 70 72 6f 67 72 61 6d 2e 20 5e 54 68 65 20 50  bprogram. ^The P
25d60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
25d70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
25d80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25d90 6d 65 6e 74 5d 2e 20 5e 54 68 65 20 58 20 61 72  ment]. ^The X ar
25da0 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
25db0 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
25dc0 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
25dd0 75 6e 65 78 70 61 6e 64 65 64 20 53 51 4c 20 74  unexpanded SQL t
25de0 65 78 74 20 6f 66 20 74 68 65 20 70 72 65 70 61  ext of the prepa
25df0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  red statement or
25e00 20 61 6e 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20   an SQL comment 
25e10 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
25e20 65 73 20 74 68 65 20 69 6e 76 6f 63 61 74 69 6f  es the invocatio
25e30 6e 20 6f 66 20 61 20 74 72 69 67 67 65 72 2e 20  n of a trigger. 
25e40 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 63   ^The callback c
25e50 61 6e 20 63 6f 6d 70 75 74 65 0a 2a 2a 20 74 68  an compute.** th
25e60 65 20 73 61 6d 65 20 74 65 78 74 20 74 68 61 74  e same text that
25e70 20 77 6f 75 6c 64 20 68 61 76 65 20 62 65 65 6e   would have been
25e80 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
25e90 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33   legacy [sqlite3
25ea0 5f 74 72 61 63 65 28 29 5d 0a 2a 2a 20 69 6e 74  _trace()].** int
25eb0 65 72 66 61 63 65 20 62 79 20 75 73 69 6e 67 20  erface by using 
25ec0 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 77  the X argument w
25ed0 68 65 6e 20 58 20 62 65 67 69 6e 73 20 77 69 74  hen X begins wit
25ee0 68 20 22 2d 2d 22 20 61 6e 64 20 69 6e 76 6f 6b  h "--" and invok
25ef0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
25f00 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 50 29 5d  expanded_sql(P)]
25f10 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
25f20 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  * [[SQLITE_TRACE
25f30 5f 50 52 4f 46 49 4c 45 5d 5d 20 3c 64 74 3e 53  _PROFILE]] <dt>S
25f40 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46  QLITE_TRACE_PROF
25f50 49 4c 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ILE</dt>.** <dd>
25f60 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45  ^An SQLITE_TRACE
25f70 5f 50 52 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63  _PROFILE callbac
25f80 6b 20 70 72 6f 76 69 64 65 73 20 61 70 70 72 6f  k provides appro
25f90 78 69 6d 61 74 65 6c 79 20 74 68 65 20 73 61 6d  ximately the sam
25fa0 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
25fb0 20 61 73 20 69 73 20 70 72 6f 76 69 64 65 64 20   as is provided 
25fc0 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
25fd0 70 72 6f 66 69 6c 65 28 29 5d 20 63 61 6c 6c 62  profile()] callb
25fe0 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 50 20 61  ack..** ^The P a
25ff0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
26000 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 70 72 65  nter to the [pre
26010 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
26020 20 61 6e 64 20 74 68 65 0a 2a 2a 20 58 20 61 72   and the.** X ar
26030 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
26040 20 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65   a 64-bit intege
26050 72 20 77 68 69 63 68 20 69 73 20 74 68 65 20 65  r which is the e
26060 73 74 69 6d 61 74 65 64 20 6f 66 0a 2a 2a 20 74  stimated of.** t
26070 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6e 61 6e  he number of nan
26080 6f 73 65 63 6f 6e 64 20 74 68 61 74 20 74 68 65  osecond that the
26090 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
260a0 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
260b0 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  .** ^The SQLITE_
260c0 54 52 41 43 45 5f 50 52 4f 46 49 4c 45 20 63 61  TRACE_PROFILE ca
260d0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
260e0 64 20 77 68 65 6e 20 74 68 65 20 73 74 61 74 65  d when the state
260f0 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 0a 2a  ment finishes..*
26100 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52  *.** [[SQLITE_TR
26110 41 43 45 5f 52 4f 57 5d 5d 20 3c 64 74 3e 53 51  ACE_ROW]] <dt>SQ
26120 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 3c 2f  LITE_TRACE_ROW</
26130 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53  dt>.** <dd>^An S
26140 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 20  QLITE_TRACE_ROW 
26150 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
26160 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 70  ked whenever a p
26170 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
26180 6d 65 6e 74 20 67 65 6e 65 72 61 74 65 73 20 61  ment generates a
26190 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 72   single row of r
261a0 65 73 75 6c 74 2e 20 20 0a 2a 2a 20 5e 54 68 65  esult.  .** ^The
261b0 20 50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61   P argument is a
261c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
261d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
261e0 65 6e 74 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  ent] and the.** 
261f0 58 20 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e  X argument is un
26200 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  used..**.** [[SQ
26210 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53 45  LITE_TRACE_CLOSE
26220 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
26230 41 43 45 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a  ACE_CLOSE</dt>.*
26240 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45  * <dd>^An SQLITE
26250 5f 54 52 41 43 45 5f 43 4c 4f 53 45 20 63 61 6c  _TRACE_CLOSE cal
26260 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
26270 20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65   when a database
26280 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  .** connection c
26290 6c 6f 73 65 73 2e 0a 2a 2a 20 5e 54 68 65 20 50  loses..** ^The P
262a0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
262b0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
262c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
262d0 6f 6e 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e  on] object.** an
262e0 64 20 74 68 65 20 58 20 61 72 67 75 6d 65 6e 74  d the X argument
262f0 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a 20 3c   is unused..** <
26300 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
26310 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 54 4d  SQLITE_TRACE_STM
26320 54 20 20 20 20 20 20 20 30 78 30 31 0a 23 64 65  T       0x01.#de
26330 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 43  fine SQLITE_TRAC
26340 45 5f 50 52 4f 46 49 4c 45 20 20 20 20 30 78 30  E_PROFILE    0x0
26350 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
26360 5f 54 52 41 43 45 5f 52 4f 57 20 20 20 20 20 20  _TRACE_ROW      
26370 20 20 30 78 30 34 0a 23 64 65 66 69 6e 65 20 53    0x04.#define S
26380 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
26390 45 20 20 20 20 20 20 30 78 30 38 0a 0a 2f 2a 0a  E      0x08../*.
263a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
263b0 20 54 72 61 63 65 20 48 6f 6f 6b 0a 2a 2a 20 4d   Trace Hook.** M
263c0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
263d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
263e0 33 5f 74 72 61 63 65 5f 76 32 28 44 2c 4d 2c 58  3_trace_v2(D,M,X
263f0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,P) interface re
26400 67 69 73 74 65 72 73 20 61 20 74 72 61 63 65 20  gisters a trace 
26410 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
26420 74 69 6f 6e 20 58 20 61 67 61 69 6e 73 74 20 5b  tion X against [
26430 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
26440 69 6f 6e 5d 20 44 2c 20 75 73 69 6e 67 20 70 72  ion] D, using pr
26450 6f 70 65 72 74 79 20 6d 61 73 6b 20 4d 0a 2a 2a  operty mask M.**
26460 20 61 6e 64 20 63 6f 6e 74 65 78 74 20 70 6f 69   and context poi
26470 6e 74 65 72 20 50 2e 20 20 5e 49 66 20 74 68 65  nter P.  ^If the
26480 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 0a 2a   X callback is.*
26490 2a 20 4e 55 4c 4c 20 6f 72 20 69 66 20 74 68 65  * NULL or if the
264a0 20 4d 20 6d 61 73 6b 20 69 73 20 7a 65 72 6f 2c   M mask is zero,
264b0 20 74 68 65 6e 20 74 72 61 63 69 6e 67 20 69 73   then tracing is
264c0 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 0a   disabled.  The.
264d0 2a 2a 20 4d 20 61 72 67 75 6d 65 6e 74 20 73 68  ** M argument sh
264e0 6f 75 6c 64 20 62 65 20 74 68 65 20 62 69 74 77  ould be the bitw
264f0 69 73 65 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e  ise OR-ed combin
26500 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 7a 65 72 6f  ation of.** zero
26510 20 6f 72 20 6d 6f 72 65 20 5b 53 51 4c 49 54 45   or more [SQLITE
26520 5f 54 52 41 43 45 5d 20 63 6f 6e 73 74 61 6e 74  _TRACE] constant
26530 73 2e 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 63  s..**.** ^Each c
26540 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 73 71  all to either sq
26550 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f 72  lite3_trace() or
26560 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
26570 32 28 29 20 6f 76 65 72 72 69 64 65 73 20 0a 2a  2() overrides .*
26580 2a 20 28 63 61 6e 63 65 6c 73 29 20 61 6e 79 20  * (cancels) any 
26590 70 72 69 6f 72 20 63 61 6c 6c 73 20 74 6f 20 73  prior calls to s
265a0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 6f  qlite3_trace() o
265b0 72 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  r sqlite3_trace_
265c0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  v2()..**.** ^The
265d0 20 58 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69   X callback is i
265e0 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
265f0 61 6e 79 20 6f 66 20 74 68 65 20 65 76 65 6e 74  any of the event
26600 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
26610 0a 2a 2a 20 6d 61 73 6b 20 4d 20 6f 63 63 75 72  .** mask M occur
26620 2e 20 20 5e 54 68 65 20 69 6e 74 65 67 65 72 20  .  ^The integer 
26630 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
26640 6d 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  m the callback i
26650 73 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 69  s currently.** i
26660 67 6e 6f 72 65 64 2c 20 74 68 6f 75 67 68 20 74  gnored, though t
26670 68 69 73 20 6d 61 79 20 63 68 61 6e 67 65 20 69  his may change i
26680 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
26690 73 2e 20 20 43 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s.  Callback.** 
266a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
266b0 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 7a 65  should return ze
266c0 72 6f 20 74 6f 20 65 6e 73 75 72 65 20 66 75 74  ro to ensure fut
266d0 75 72 65 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ure compatibilit
266e0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 74 72 61 63  y..**.** ^A trac
266f0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
26700 76 6f 6b 65 64 20 77 69 74 68 20 66 6f 75 72 20  voked with four 
26710 61 72 67 75 6d 65 6e 74 73 3a 20 63 61 6c 6c 62  arguments: callb
26720 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a 2a  ack(T,C,P,X)..**
26730 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e 74   ^The T argument
26740 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
26750 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 0a 2a 2a  SQLITE_TRACE].**
26760 20 63 6f 6e 73 74 61 6e 74 73 20 74 6f 20 69 6e   constants to in
26770 64 69 63 61 74 65 20 77 68 79 20 74 68 65 20 63  dicate why the c
26780 61 6c 6c 62 61 63 6b 20 77 61 73 20 69 6e 76 6f  allback was invo
26790 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 43 20 61  ked..** ^The C a
267a0 72 67 75 6d 65 6e 74 20 69 73 20 61 20 63 6f 70  rgument is a cop
267b0 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 78 74  y of the context
267c0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 54 68 65   pointer..** The
267d0 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65 6e   P and X argumen
267e0 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73 20  ts are pointers 
267f0 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20 64  whose meanings d
26800 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a 2a  epend on T..**.*
26810 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72  * The sqlite3_tr
26820 61 63 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ace_v2() interfa
26830 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  ce is intended t
26840 6f 20 72 65 70 6c 61 63 65 20 74 68 65 20 6c 65  o replace the le
26850 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
26860 65 73 20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63  es [sqlite3_trac
26870 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
26880 33 5f 70 72 6f 66 69 6c 65 28 29 5d 2c 20 62 6f  3_profile()], bo
26890 74 68 20 6f 66 20 77 68 69 63 68 0a 2a 2a 20 61  th of which.** a
268a0 72 65 20 64 65 70 72 65 63 61 74 65 64 2e 0a 2a  re deprecated..*
268b0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
268c0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76   sqlite3_trace_v
268d0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20  2(.  sqlite3*,. 
268e0 20 75 6e 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c   unsigned uMask,
268f0 0a 20 20 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63  .  int(*xCallbac
26900 6b 29 28 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64  k)(unsigned,void
26910 2a 2c 76 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a  *,void*,void*),.
26920 20 20 76 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a    void *pCtx.);.
26930 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26940 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20   Query Progress 
26950 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
26960 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
26970 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26980 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
26990 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
269a0 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
269b0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
269c0 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
269d0 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
269e0 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
269f0 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
26a00 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
26a10 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
26a20 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
26a30 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
26a40 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
26a50 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
26a60 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
26a70 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
26a80 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
26a90 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
26aa0 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
26ab0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
26ac0 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
26ad0 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
26ae0 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
26af0 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
26b00 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
26b10 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
26b20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69  N is the approxi
26b30 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a  mate number of .
26b40 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
26b50 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
26b60 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
26b70 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
26b80 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
26b90 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
26ba0 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e  llback X.  ^If N
26bb0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e   is less than on
26bc0 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72  e then the progr
26bd0 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69  ess.** handler i
26be0 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
26bf0 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
26c00 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
26c10 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
26c20 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
26c30 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
26c40 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
26c50 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
26c60 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
26c70 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
26c80 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
26c90 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
26ca0 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
26cb0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
26cc0 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
26cd0 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
26ce0 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
26cf0 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
26d00 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
26d10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
26d20 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
26d30 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
26d40 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
26d50 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
26d60 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
26d70 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
26d80 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
26d90 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
26da0 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
26db0 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
26dc0 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
26dd0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
26de0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
26df0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
26e00 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
26e10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26e20 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
26e30 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
26e40 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
26e50 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
26e60 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
26e70 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
26e80 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
26e90 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
26ea0 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
26eb0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
26ec0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
26ed0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51  agraph..**.*/.SQ
26ee0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
26ef0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
26f00 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
26f10 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
26f20 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
26f30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
26f40 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
26f50 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
26f60 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52 3a 20  ** CONSTRUCTOR: 
26f70 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
26f80 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70  hese routines op
26f90 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74  en an SQLite dat
26fa0 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70  abase file as sp
26fb0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a  ecified by the .
26fc0 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  ** filename argu
26fd0 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e  ment. ^The filen
26fe0 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ame argument is 
26ff0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
27000 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  TF-8 for.** sqli
27010 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
27020 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
27030 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69   and as UTF-16 i
27040 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
27050 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73  e.** order for s
27060 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
27070 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63   ^(A [database c
27080 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
27090 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20  e is usually.** 
270a0 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44  returned in *ppD
270b0 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72  b, even if an er
270c0 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65  ror occurs.  The
270d0 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20   only exception 
270e0 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51  is that.** if SQ
270f0 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
27100 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
27110 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73  y to hold the [s
27120 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a  qlite3] object,.
27130 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62  ** a NULL will b
27140 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a  e written into *
27150 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20  ppDb instead of 
27160 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
27170 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62   [sqlite3].** ob
27180 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65  ject.)^ ^(If the
27190 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
271a0 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61  ned (and/or crea
271b0 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c  ted) successfull
271c0 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49  y, then.** [SQLI
271d0 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e  TE_OK] is return
271e0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61  ed.  Otherwise a
271f0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
27200 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54  s returned.)^ ^T
27210 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
27220 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c  rrmsg()] or [sql
27230 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d  ite3_errmsg16()]
27240 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65   routines can be
27250 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a   used to obtain.
27260 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61  ** an English la
27270 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69  nguage descripti
27280 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  on of the error 
27290 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
272a0 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66  ure of any.** of
272b0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   the sqlite3_ope
272c0 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  n() routines..**
272d0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
272e0 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c 20 62   encoding will b
272f0 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61 74 61  e UTF-8 for data
27300 62 61 73 65 73 20 63 72 65 61 74 65 64 20 75 73  bases created us
27310 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  ing.** sqlite3_o
27320 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33  pen() or sqlite3
27330 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e 54 68  _open_v2().  ^Th
27340 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
27350 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73 65 73  ng for databases
27360 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73 69 6e  .** created usin
27370 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  g sqlite3_open16
27380 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46 2d 31  () will be UTF-1
27390 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  6 in the native 
273a0 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 0a 2a  byte order..**.*
273b0 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
273c0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
273d0 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
273e0 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
273f0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
27400 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
27410 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
27420 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
27430 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
27440 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
27450 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
27460 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
27470 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
27480 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
27490 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
274a0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
274b0 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
274c0 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
274d0 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
274e0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
274f0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
27500 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
27510 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
27520 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
27530 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
27540 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
27550 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
27560 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
27570 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
27580 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
27590 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
275a0 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
275b0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
275c0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
275d0 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
275e0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
275f0 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
27600 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
27610 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
27620 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
27630 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
27640 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
27650 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
27660 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27670 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
27680 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
27690 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
276a0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
276b0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
276c0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
276d0 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
276e0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
276f0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
27700 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
27710 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
27720 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
27730 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
27740 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
27750 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
27760 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
27770 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
27780 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
27790 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
277a0 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
277b0 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
277c0 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
277d0 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
277e0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
277f0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
27800 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
27810 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
27820 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
27830 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
27840 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
27850 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
27860 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
27870 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
27880 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
27890 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
278a0 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
278b0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
278c0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
278d0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
278e0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
278f0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
27900 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
27910 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
27920 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
27930 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
27940 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
27950 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
27960 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
27970 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
27980 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
27990 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
279a0 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
279b0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
279c0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
279d0 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
279e0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
279f0 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
27a00 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
27a10 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
27a20 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
27a30 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
27a40 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
27a50 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
27a60 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
27a70 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
27a80 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
27a90 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
27aa0 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
27ab0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
27ac0 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
27ad0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
27ae0 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
27af0 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
27b00 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
27b10 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
27b20 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
27b30 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
27b40 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
27b50 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
27b60 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
27b70 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
27b80 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
27b90 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
27ba0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
27bb0 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
27bc0 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
27bd0 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
27be0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
27bf0 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
27c00 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
27c10 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
27c20 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
27c30 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
27c40 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
27c50 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
27c60 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
27c70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
27c80 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
27c90 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
27ca0 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
27cb0 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
27cc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
27cd0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
27ce0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
27cf0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
27d00 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
27d10 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
27d20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
27d30 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
27d40 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
27d50 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
27d60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
27d70 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
27d80 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
27d90 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
27da0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
27db0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
27dc0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
27dd0 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
27de0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
27df0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
27e00 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
27e10 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
27e20 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
27e30 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
27e40 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
27e50 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
27e60 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
27e70 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
27e80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
27e90 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
27ea0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
27eb0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
27ec0 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
27ed0 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
27ee0 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
27ef0 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
27f00 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
27f10 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
27f20 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
27f30 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
27f40 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
27f50 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
27f60 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
27f70 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
27f80 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
27f90 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
27fa0 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
27fb0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
27fc0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
27fd0 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
27fe0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
27ff0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
28000 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
28010 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
28020 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
28030 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
28040 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
28050 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
28060 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
28070 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
28080 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
28090 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
280a0 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
280b0 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
280c0 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
280d0 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
280e0 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
280f0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
28100 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
28110 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
28120 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
28130 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
28140 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
28150 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
28160 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
28170 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
28180 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
28190 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
281a0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
281b0 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
281c0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
281d0 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
281e0 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
281f0 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
28200 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
28210 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
28220 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
28230 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
28240 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
28250 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
28260 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
28270 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
28280 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
28290 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
282a0 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
282b0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
282c0 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
282d0 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
282e0 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
282f0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
28300 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
28310 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
28320 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
28330 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
28340 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
28350 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
28360 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
28370 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
28380 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
28390 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
283a0 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
283b0 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
283c0 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
283d0 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
283e0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
283f0 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
28400 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
28410 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
28420 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
28430 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
28440 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
28450 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
28460 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
28470 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
28480 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
28490 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
284a0 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
284b0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
284c0 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
284d0 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
284e0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
284f0 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
28500 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
28510 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
28520 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
28530 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
28540 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
28550 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
28560 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
28570 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
28580 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
28590 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
285a0 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
285b0 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
285c0 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
285d0 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
285e0 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
285f0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
28600 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
28610 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77 73 2c  ** ^(On windows,
28620 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
28630 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
28640 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
28650 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
28660 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
28670 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  ).)^.**.** [[cor
28680 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
28690 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
286a0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
286b0 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
286c0 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
286d0 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
286e0 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
286f0 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
28700 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
28710 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
28720 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
28730 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20 62 75  QLite and its bu
28740 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d 20 69  ilt-in [VFSes] i
28750 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a 2a 20  nterpret the.** 
28760 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72 79 20  following query 
28770 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a  parameters:.**.*
28780 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e  * <ul>.**   <li>
28790 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68   <b>vfs</b>: ^Th
287a0 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74 65  e "vfs" paramete
287b0 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f  r may be used to
287c0 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d   specify the nam
287d0 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46  e of.**     a VF
287e0 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72  S object that pr
287f0 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72 61  ovides the opera
28800 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
28810 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c  rface that shoul
28820 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64  d.**     be used
28830 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64   to access the d
28840 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20  atabase file on 
28850 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f  disk. ^If this o
28860 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a  ption is set to.
28870 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20  **     an empty 
28880 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61 75  string the defau
28890 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73  lt VFS object is
288a0 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69   used. ^Specifyi
288b0 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a  ng an unknown.**
288c0 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20 65       VFS is an e
288d0 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65  rror. ^If sqlite
288e0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
288f0 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73 20  sed and the vfs 
28900 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
28910 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74   present, then t
28920 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65 64  he VFS specified
28930 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74   by the option t
28940 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65 20  akes precedence 
28950 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20  over.**     the 
28960 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
28970 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
28980 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
28990 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
289a0 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c     <li> <b>mode<
289b0 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20  /b>: ^(The mode 
289c0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
289d0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
289e0 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20  ro", "rw",.**   
289f0 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d    "rwc", or "mem
28a00 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67  ory". Attempting
28a10 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e   to set it to an
28a20 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73  y other value is
28a30 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72  .**     an error
28a40 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
28a50 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
28a60 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
28a70 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
28a80 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
28a90 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
28aa0 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
28ab0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
28ac0 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
28ad0 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
28ae0 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
28af0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
28b00 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65  en_v2(). ^If the
28b10 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20   mode option is 
28b20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22  set to .**     "
28b30 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61  rw", then the da
28b40 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
28b50 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20   for read-write 
28b60 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29  (but not create)
28b70 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
28b80 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50   as if SQLITE_OP
28b90 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62 75  EN_READWRITE (bu
28ba0 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45  t not SQLITE_OPE
28bb0 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a  N_CREATE) had .*
28bc0 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20  *     been set. 
28bd0 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73 20  ^Value "rwc" is 
28be0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
28bf0 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20  tting both .**  
28c00 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52     SQLITE_OPEN_R
28c10 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c  EADWRITE and SQL
28c20 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e  ITE_OPEN_CREATE.
28c30 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f    ^If the mode o
28c40 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20  ption is.**     
28c50 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20  set to "memory" 
28c60 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d  then a pure [in-
28c70 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d  memory database]
28c80 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61 64   that never read
28c90 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74  s.**     or writ
28ca0 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20  es from disk is 
28cb0 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20  used. ^It is an 
28cc0 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79  error to specify
28cd0 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20   a value for.** 
28ce0 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72      the mode par
28cf0 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20 6c  ameter that is l
28d00 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65 20  ess restrictive 
28d10 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69 66  than that specif
28d20 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68  ied by.**     th
28d30 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20 69  e flags passed i
28d40 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  n the third para
28d50 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
28d60 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
28d70 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68  *   <li> <b>cach
28d80 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68  e</b>: ^The cach
28d90 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
28da0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
28db0 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20   "shared" or.** 
28dc0 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e      "private". ^
28dd0 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73  Setting it to "s
28de0 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76 61  hared" is equiva
28df0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
28e00 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  the.**     SQLIT
28e10 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
28e20 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c  HE bit in the fl
28e30 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ags argument pas
28e40 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71  sed to.**     sq
28e50 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
28e60 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63 61   ^Setting the ca
28e70 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  che parameter to
28e80 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a   "private" is .*
28e90 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74  *     equivalent
28ea0 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20   to setting the 
28eb0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
28ec0 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a  ATECACHE bit..**
28ed0 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33       ^If sqlite3
28ee0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73  _open_v2() is us
28ef0 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63 68  ed and the "cach
28f00 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  e" parameter is 
28f10 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20  present in.**   
28f20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65    a URI filename
28f30 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72  , its value over
28f40 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76 69  rides any behavi
28f50 6f 72 20 72 65 71 75 65 73 74 65 64 20 62 79 20  or requested by 
28f60 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53  setting.**     S
28f70 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
28f80 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54  TECACHE or SQLIT
28f90 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
28fa0 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20  HE flag..**.**  
28fb0 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e  <li> <b>psow</b>
28fc0 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61  : ^The psow para
28fd0 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65 73 20  meter indicates 
28fe0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
28ff0 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77 65 72  he.**     [power
29000 73 61 66 65 20 6f 76 65 72 77 72 69 74 65 5d 20  safe overwrite] 
29010 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20 6f 72  property does or
29020 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c 79 20   does not apply 
29030 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20 73 74  to the.**     st
29040 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e 20 77  orage media on w
29050 68 69 63 68 20 74 68 65 20 64 61 74 61 62 61 73  hich the databas
29060 65 20 66 69 6c 65 20 72 65 73 69 64 65 73 2e 0a  e file resides..
29070 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e  **.**  <li> <b>n
29080 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20  olock</b>: ^The 
29090 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72  nolock parameter
290a0 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
290b0 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ery parameter.**
290c0 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65       which if se
290d0 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20  t disables file 
290e0 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62  locking in rollb
290f0 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65  ack journal mode
29100 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20  s.  This.**     
29110 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63  is useful for ac
29120 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61  cessing a databa
29130 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74  se on a filesyst
29140 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  em that does not
29150 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20  .**     support 
29160 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f  locking.  Cautio
29170 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72  n:  Database cor
29180 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ruption might re
29190 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20  sult if two.**  
291a0 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65     or more proce
291b0 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68  sses write to th
291c0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
291d0 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74  and any one of t
291e0 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63  hose.**     proc
291f0 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63  esses uses noloc
29200 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  k=1..**.**  <li>
29210 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62   <b>immutable</b
29220 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c  >: ^The immutabl
29230 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  e parameter is a
29240 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a   boolean query.*
29250 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20  *     parameter 
29260 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
29270 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
29280 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20   file is stored 
29290 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f  on.**     read-o
292a0 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65  nly media.  ^Whe
292b0 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73  n immutable is s
292c0 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  et, SQLite assum
292d0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  es that the.**  
292e0 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65     database file
292f0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
29300 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72  ed, even by a pr
29310 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65  ocess with highe
29320 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65  r.**     privile
29330 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64  ge, and so the d
29340 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
29350 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20  d read-only and 
29360 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20  all locking.**  
29370 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65     and change de
29380 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62  tection is disab
29390 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53  led.  Caution: S
293a0 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74  etting the immut
293b0 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70  able.**     prop
293c0 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61  erty on a databa
293d0 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
293e0 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65  s in fact change
293f0 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20   can result.**  
29400 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20     in incorrect 
29410 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e  query results an
29420 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
29430 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a  RUPT] errors..**
29440 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b       See also: [
29450 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
29460 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20  UTABLE]..**     
29470 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a    .** </ul>.**.*
29480 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
29490 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
294a0 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
294b0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
294c0 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
294d0 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
294e0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
294f0 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
29500 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
29510 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
29520 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
29530 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
29540 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
29550 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
29560 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
29570 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
29580 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
29590 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
295a0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
295b0 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
295c0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
295d0 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
295e0 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
295f0 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
29600 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
29610 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
29620 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
29630 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
29640 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
29650 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
29660 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
29670 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
29680 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
29690 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
296a0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
296b0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
296c0 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
296d0 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
296e0 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
296f0 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
29700 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
29710 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
29720 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
29730 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
29740 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
29750 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
29760 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
29770 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
29780 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
29790 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
297a0 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
297b0 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
297c0 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
297d0 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
297e0 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
297f0 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
29800 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
29810 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
29820 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
29830 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
29840 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
29850 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
29860 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
29870 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
29880 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
29890 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
298a0 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
298b0 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
298c0 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
298d0 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
298e0 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
298f0 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
29900 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
29910 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
29920 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
29930 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
29940 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
29950 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
29960 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
29970 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
29980 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
29990 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
299a0 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
299b0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
299c0 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
299d0 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
299e0 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
299f0 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
29a00 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
29a10 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
29a20 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
29a30 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74  =unix-dotfile <t
29a40 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
29a50 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
29a60 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
29a70 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
29a80 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65  FS "unix-dotfile
29a90 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ".**          th
29aa0 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65  at uses dot-file
29ab0 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f  s in place of po
29ac0 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63  six advisory loc
29ad0 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  king..** <tr><td
29ae0 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
29af0 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
29b00 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
29b10 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
29b20 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
29b30 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
29b40 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
29b50 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
29b60 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
29b70 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
29b80 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
29b90 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
29ba0 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
29bb0 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
29bc0 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
29bd0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
29be0 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
29bf0 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
29c00 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
29c10 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
29c20 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
29c30 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
29c40 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
29c50 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
29c60 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
29c70 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
29c80 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
29c90 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
29ca0 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
29cb0 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
29cc0 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
29cd0 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
29ce0 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
29cf0 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
29d00 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
29d10 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
29d20 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
29d30 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
29d40 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
29d50 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
29d60 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
29d70 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
29d80 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
29d90 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
29da0 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
29db0 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
29dc0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
29dd0 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
29de0 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
29df0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
29e00 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
29e10 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
29e20 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
29e30 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
29e40 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
29e50 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
29e60 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
29e70 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
29e80 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
29e90 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
29ea0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
29eb0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
29ec0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
29ed0 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
29ee0 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
29ef0 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
29f00 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
29f10 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
29f20 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
29f30 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
29f40 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
29f50 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
29f60 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
29f70 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
29f80 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
29f90 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
29fa0 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
29fb0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
29fc0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
29fd0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
29fe0 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
29ff0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
2a000 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
2a010 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
2a020 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
2a030 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
2a040 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
2a050 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
2a060 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2a070 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  t sqlite3_open16
2a080 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  (.  const void *
2a090 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
2a0a0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
2a0b0 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73   (UTF-16) */.  s
2a0c0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
2a0d0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
2a0e0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
2a0f0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
2a100 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
2a110 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68  n_v2(.  const ch
2a120 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  ar *filename,   
2a130 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
2a140 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a  name (UTF-8) */.
2a150 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
2a160 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54  ,         /* OUT
2a170 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
2a180 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67  le */.  int flag
2a190 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  s,              
2a1a0 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f  /* Flags */.  co
2a1b0 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20  nst char *zVfs  
2a1c0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
2a1d0 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75   VFS module to u
2a1e0 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  se */.);../*.** 
2a1f0 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
2a200 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20   Values For URI 
2a210 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
2a220 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69   These are utili
2a230 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65  ty routines, use
2a240 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65  ful to VFS imple
2a250 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74  mentations, that
2a260 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65   check.** to see
2a270 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66   if a database f
2a280 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68  ile was a URI th
2a290 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73  at contained a s
2a2a0 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a  pecific query .*
2a2b0 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64  * parameter, and
2a2c0 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74   if so obtains t
2a2d0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74  he value of that
2a2e0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
2a2f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20  ..**.** If F is 
2a300 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2a310 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61  ename pointer pa
2a320 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
2a330 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  pen() method of 
2a340 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d  .** a VFS implem
2a350 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68  entation when th
2a360 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
2a370 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73  r to xOpen() has
2a380 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65   one or .** more
2a390 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
2a3a0 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51  OPEN_URI] or [SQ
2a3b0 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
2a3c0 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a  B] bits set and.
2a3d0 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65  ** P is the name
2a3e0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61   of the query pa
2a3f0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a  rameter, then.**
2a400 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
2a410 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
2a420 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rns the value of
2a430 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65   the P.** parame
2a440 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73  ter if it exists
2a450 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   or a NULL point
2a460 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74  er if P does not
2a470 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a   appear as a .**
2a480 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
2a490 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20   on F.  If P is 
2a4a0 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  a query paramete
2a4b0 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f  r of F.** has no
2a4c0 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c   explicit value,
2a4d0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
2a4e0 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
2a4f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f   returns.** a po
2a500 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74  inter to an empt
2a510 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  y string..**.** 
2a520 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
2a530 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
2a540 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74  outine assumes t
2a550 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65  hat P is a boole
2a560 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  an.** parameter 
2a570 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65  and returns true
2a580 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30   (1) or false (0
2a590 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74  ) according to t
2a5a0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50  he value.** of P
2a5b0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  .  The sqlite3_u
2a5c0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
2a5d0 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
2a5e0 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68  s true (1) if th
2a5f0 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75  e.** value of qu
2a600 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
2a610 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c  is one of "yes",
2a620 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22   "true", or "on"
2a630 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20   in any.** case 
2a640 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  or if the value 
2a650 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f  begins with a no
2a660 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20  n-zero number.  
2a670 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  The .** sqlite3_
2a680 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
2a690 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  B) routines retu
2a6a0 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66  rns false (0) if
2a6b0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a   the value of.**
2a6c0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
2a6d0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f   P is one of "no
2a6e0 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22  ", "false", or "
2a6f0 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65  off" in any case
2a700 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61   or.** if the va
2a710 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
2a720 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20  a numeric zero. 
2a730 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71   If P is not a q
2a740 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65  uery.** paramete
2a750 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65  r on F or if the
2a760 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64   value of P is d
2a770 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e  oes not match an
2a780 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76  y of the.** abov
2a790 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
2a7a0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
2a7b0 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30  B) returns (B!=0
2a7c0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )..**.** The sql
2a7d0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46  ite3_uri_int64(F
2a7e0 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f  ,P,D) routine co
2a7f0 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65  nverts the value
2a800 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20   of P into a.** 
2a810 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
2a820 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e  teger and return
2a830 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20  s that integer, 
2a840 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e  or D if P does n
2a850 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66  ot.** exist.  If
2a860 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
2a870 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  is something oth
2a880 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67  er than an integ
2a890 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f  er, then.** zero
2a8a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2a8b0 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e   .** If F is a N
2a8c0 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
2a8d0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
2a8e0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
2a8f0 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a  urns NULL and.**
2a900 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
2a910 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75  lean(F,P,B) retu
2a920 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20  rns B.  If F is 
2a930 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  not a NULL point
2a940 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74  er and.** is not
2a950 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
2a960 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65   pathname pointe
2a970 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61  r that SQLite pa
2a980 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f  ssed into the xO
2a990 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f  pen.** VFS metho
2a9a0 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
2a9b0 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75  vior of this rou
2a9c0 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65  tine is undefine
2a9d0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a  d and probably.*
2a9e0 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a  * undesirable..*
2a9f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
2aa00 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2aa10 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
2aa20 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
2aa30 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
2aa40 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54   *zParam);.SQLIT
2aa50 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2aa60 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f  3_uri_boolean(co
2aa70 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c  nst char *zFile,
2aa80 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
2aa90 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c  ram, int bDefaul
2aaa0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  t);.SQLITE_API s
2aab0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
2aac0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
2aad0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
2aae0 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
2aaf0 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
2ab00 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
2ab10 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
2ab20 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ges.** METHOD: s
2ab30 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66  qlite3.**.** ^If
2ab40 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2ab50 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
2ab60 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77  all associated w
2ab70 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ith .** [databas
2ab80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
2ab90 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  failed, then the
2aba0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
2abb0 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  (D) interface.**
2abc0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2abd0 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
2abe0 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
2abf0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
2ac00 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c   that.** API cal
2ac10 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73  l..** If the mos
2ac20 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
2ac30 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c  l was successful
2ac40 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
2ac50 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
2ac60 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
2ac70 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  ) is undefined..
2ac80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2ac90 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
2aca0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
2acb0 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
2acc0 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
2acd0 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
2ace0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
2acf0 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
2ad00 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
2ad10 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
2ad20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
2ad30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
2ad40 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
2ad50 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
2ad60 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
2ad70 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
2ad80 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
2ad90 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
2ada0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
2adb0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
2adc0 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
2add0 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
2ade0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
2adf0 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
2ae00 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
2ae10 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
2ae20 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
2ae30 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
2ae40 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
2ae50 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
2ae60 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
2ae70 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
2ae80 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
2ae90 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
2aea0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
2aeb0 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
2aec0 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ns.)^.**.** ^The
2aed0 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
2aee0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2aef0 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d  rns the English-
2af00 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a  language text.**
2af10 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
2af20 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  the [result code
2af30 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20  ], as UTF-8..** 
2af40 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
2af50 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
2af60 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
2af70 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  aged internally.
2af80 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  ** and must not 
2af90 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20  be freed by the 
2afa0 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a  application)^..*
2afb0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
2afc0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
2afd0 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
2afe0 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
2aff0 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
2b000 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
2b010 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
2b020 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
2b030 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
2b040 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
2b050 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
2b060 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
2b070 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
2b080 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
2b090 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
2b0a0 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
2b0b0 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
2b0c0 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
2b0d0 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
2b0e0 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
2b0f0 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
2b100 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
2b110 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
2b120 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
2b130 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2b140 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
2b150 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
2b160 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
2b170 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
2b180 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
2b190 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
2b1a0 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
2b1b0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
2b1c0 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
2b1d0 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
2b1e0 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
2b1f0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
2b200 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
2b210 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
2b220 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
2b230 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
2b240 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
2b250 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
2b260 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
2b270 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
2b280 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
2b290 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
2b2a0 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
2b2b0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
2b2c0 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
2b2d0 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  e set..*/.SQLITE
2b2e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2b2f0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
2b300 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50   *db);.SQLITE_AP
2b310 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  I int sqlite3_ex
2b320 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
2b330 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c  qlite3 *db);.SQL
2b340 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2b350 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
2b360 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  sg(sqlite3*);.SQ
2b370 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2b380 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
2b390 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
2b3a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2b3b0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2b3c0 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a  errstr(int);../*
2b3d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72  .** CAPI3REF: Pr
2b3e0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2b3f0 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
2b400 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
2b410 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
2b420 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
2b430 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
2b440 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
2b450 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
2b460 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
2b470 6e 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62  nt that.** has b
2b480 65 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74  een compiled int
2b490 6f 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e  o binary form an
2b4a0 64 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65  d is ready to be
2b4b0 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a   evaluated..**.*
2b4c0 2a 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20  * Think of each 
2b4d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
2b4e0 20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70   a separate comp
2b4f0 75 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54  uter program.  T
2b500 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
2b510 51 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63  QL text is sourc
2b520 65 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61  e code.  A prepa
2b530 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  red statement ob
2b540 6a 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20  ject .** is the 
2b550 63 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20  compiled object 
2b560 63 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d  code.  All SQL m
2b570 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
2b580 20 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61   into a.** prepa
2b590 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65  red statement be
2b5a0 66 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72  fore it can be r
2b5b0 75 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  un..**.** The li
2b5c0 66 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72  fe-cycle of a pr
2b5d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b5e0 20 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20   object usually 
2b5f0 67 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a  goes like this:.
2b600 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
2b610 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72  i> Create the pr
2b620 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b630 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
2b640 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2b650 32 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  2()]..** <li> Bi
2b660 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61  nd values to [pa
2b670 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
2b680 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2b690 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
2b6a0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
2b6b0 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
2b6c0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2b6d0 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
2b6e0 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
2b6f0 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72  li> Reset the pr
2b700 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b710 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2b720 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f  reset()] then go
2b730 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f   back.**      to
2b740 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69   step 2.  Do thi
2b750 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74  s zero or more t
2b760 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65  imes..** <li> De
2b770 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74  stroy the object
2b780 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
2b790 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20  finalize()]..** 
2b7a0 3c 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66  </ol>.*/.typedef
2b7b0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2b7c0 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d  stmt sqlite3_stm
2b7d0 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  t;../*.** CAPI3R
2b7e0 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d  EF: Run-time Lim
2b7f0 69 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  its.** METHOD: s
2b800 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54  qlite3.**.** ^(T
2b810 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
2b820 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
2b830 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
2b840 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
2b850 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
2b860 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
2b870 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
2b880 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2b890 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
2b8a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
2b8b0 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
2b8c0 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
2b8d0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
2b8e0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
2b8f0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
2b900 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
2b910 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
2b920 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
2b930 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
2b940 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
2b950 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2b960 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
2b970 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
2b980 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
2b990 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
2b9a0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
2b9b0 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
2b9c0 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
2b9d0 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
2b9e0 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
2b9f0 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
2ba00 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
2ba10 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
2ba20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
2ba30 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
2ba40 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
2ba50 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
2ba60 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
2ba70 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
2ba80 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
2ba90 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
2baa0 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
2bab0 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
2bac0 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
2bad0 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
2bae0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
2baf0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
2bb00 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
2bb10 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
2bb20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
2bb30 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
2bb40 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
2bb50 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
2bb60 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
2bb70 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
2bb80 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
2bb90 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
2bba0 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
2bbb0 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
2bbc0 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
2bbd0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
2bbe0 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
2bbf0 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
2bc00 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
2bc10 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
2bc20 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
2bc30 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
2bc40 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
2bc50 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
2bc60 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
2bc70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
2bc80 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
2bc90 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
2bca0 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
2bcb0 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
2bcc0 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
2bcd0 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
2bce0 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
2bcf0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
2bd00 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
2bd10 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
2bd20 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
2bd30 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
2bd40 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
2bd50 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
2bd60 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
2bd70 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
2bd80 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
2bd90 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
2bda0 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
2bdb0 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
2bdc0 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
2bdd0 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
2bde0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
2bdf0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
2be00 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
2be10 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
2be20 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
2be30 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
2be40 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
2be50 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
2be60 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
2be70 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
2be80 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
2be90 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
2bea0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
2beb0 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
2bec0 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
2bed0 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
2bee0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
2bef0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2bf00 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
2bf10 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
2bf20 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
2bf30 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
2bf40 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
2bf50 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
2bf60 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
2bf70 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
2bf80 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
2bf90 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
2bfa0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2bfb0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
2bfc0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
2bfd0 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
2bfe0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2bff0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
2c000 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
2c010 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
2c020 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
2c030 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
2c040 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
2c050 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
2c060 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
2c070 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
2c080 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
2c090 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
2c0a0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
2c0b0 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
2c0c0 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
2c0d0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
2c0e0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
2c0f0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
2c100 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2c110 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
2c120 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
2c130 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
2c140 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
2c150 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
2c160 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
2c170 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
2c180 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
2c190 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
2c1a0 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
2c1b0 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
2c1c0 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
2c1d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2c1e0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
2c1f0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2c200 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
2c210 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2c220 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2c230 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
2c240 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
2c250 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2c260 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
2c270 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
2c280 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
2c290 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2c2a0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
2c2b0 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
2c2c0 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
2c2d0 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
2c2e0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2c2f0 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
2c300 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2c310 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
2c320 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
2c330 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
2c340 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
2c350 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
2c360 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
2c370 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2c380 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
2c390 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
2c3a0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
2c3b0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
2c3c0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
2c3d0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2c3e0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
2c3f0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
2c400 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
2c410 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
2c420 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
2c430 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
2c440 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
2c450 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
2c460 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
2c470 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
2c480 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
2c490 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2c4a0 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
2c4b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
2c4c0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
2c4d0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
2c4e0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
2c4f0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
2c500 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
2c510 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
2c520 49 66 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  If [sqlite3_prep
2c530 61 72 65 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  are_v2()] or.** 
2c540 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 74  the equivalent t
2c550 72 69 65 73 20 74 6f 20 61 6c 6c 6f 63 61 74 65  ries to allocate
2c560 20 73 70 61 63 65 20 66 6f 72 20 6d 6f 72 65 20   space for more 
2c570 74 68 61 6e 20 74 68 69 73 20 6d 61 6e 79 20 6f  than this many o
2c580 70 63 6f 64 65 73 0a 2a 2a 20 69 6e 20 61 20 73  pcodes.** in a s
2c590 69 6e 67 6c 65 20 70 72 65 70 61 72 65 64 20 73  ingle prepared s
2c5a0 74 61 74 65 6d 65 6e 74 2c 20 61 6e 20 53 51 4c  tatement, an SQL
2c5b0 49 54 45 5f 4e 4f 4d 45 4d 20 65 72 72 6f 72 20  ITE_NOMEM error 
2c5c0 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
2c5d0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
2c5e0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
2c5f0 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
2c600 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2c610 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
2c620 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
2c630 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2c640 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
2c650 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
2c660 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
2c670 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
2c680 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
2c690 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
2c6a0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
2c6b0 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
2c6c0 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
2c6d0 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
2c6e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
2c6f0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
2c700 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
2c710 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
2c720 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
2c730 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
2c740 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
2c750 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
2c760 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2c770 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
2c780 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
2c790 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
2c7a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
2c7b0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
2c7c0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
2c7d0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2c7e0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
2c7f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
2c800 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
2c810 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
2c820 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
2c830 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
2c840 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
2c850 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
2c860 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
2c870 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
2c880 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
2c890 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
2c8a0 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
2c8b0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
2c8c0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f  [SQLITE_LIMIT_WO
2c8d0 52 4b 45 52 5f 54 48 52 45 41 44 53 5d 5d 20 5e  RKER_THREADS]] ^
2c8e0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
2c8f0 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
2c900 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
2c910 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
2c920 6f 66 20 61 75 78 69 6c 69 61 72 79 20 77 6f 72  of auxiliary wor
2c930 6b 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74  ker threads that
2c940 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 70 72   a single.** [pr
2c950 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c960 5d 20 6d 61 79 20 73 74 61 72 74 2e 3c 2f 64 64  ] may start.</dd
2c970 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
2c980 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
2c990 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
2c9a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
2c9b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c9c0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
2c9d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2c9e0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2c9f0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
2ca00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ca10 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2ca20 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
2ca30 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
2ca40 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
2ca50 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
2ca60 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
2ca70 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2ca80 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
2ca90 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
2caa0 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
2cab0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
2cac0 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
2cad0 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
2cae0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
2caf0 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
2cb00 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
2cb10 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
2cb20 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
2cb30 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
2cb40 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
2cb50 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
2cb60 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
2cb70 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
2cb80 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
2cb90 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
2cba0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
2cbb0 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 20  WORKER_THREADS  
2cbc0 20 20 20 20 20 20 20 20 20 31 31 0a 0a 0a 2f 2a           11.../*
2cbd0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2cbe0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
2cbf0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
2cc00 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
2cc10 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
2cc20 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2cc30 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  3.** CONSTRUCTOR
2cc40 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2cc50 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
2cc60 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
2cc70 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
2cc80 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
2cc90 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
2cca0 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
2ccb0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2ccc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
2ccd0 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
2cce0 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
2ccf0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
2cd00 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
2cd10 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
2cd20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2cd30 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
2cd40 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
2cd50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
2cd60 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
2cd70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2cd80 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
2cd90 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
2cda0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
2cdb0 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
2cdc0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
2cdd0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
2cde0 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
2cdf0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
2ce00 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
2ce10 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
2ce20 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2ce30 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
2ce40 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
2ce50 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
2ce60 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
2ce70 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2ce80 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
2ce90 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
2cea0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
2ceb0 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2cec0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
2ced0 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
2cee0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2cef0 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 70 6f   ^If nByte is po
2cf00 73 69 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  sitive, then it 
2cf10 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2cf20 20 6f 66 20 62 79 74 65 73 20 72 65 61 64 20 66   of bytes read f
2cf30 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49 66 20 6e  rom zSql.  ^If n
2cf40 42 79 74 65 20 69 73 20 7a 65 72 6f 2c 20 74 68  Byte is zero, th
2cf50 65 6e 20 6e 6f 20 70 72 65 70 61 72 65 64 0a 2a  en no prepared.*
2cf60 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 67  * statement is g
2cf70 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20 49 66 20  enerated..** If 
2cf80 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
2cf90 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
2cfa0 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
2cfb0 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
2cfc0 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73 20 61 20  n.** there is a 
2cfd0 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63  small performanc
2cfe0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 70  e advantage to p
2cff0 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
2d000 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
2d010 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
2d020 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
2d030 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
2d040 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
2d050 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
2d060 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  tor..**.** ^If p
2d070 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
2d080 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
2d090 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
2d0a0 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
2d0b0 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
2d0c0 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
2d0d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
2d0e0 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
2d0f0 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
2d100 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
2d110 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
2d120 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
2d130 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
2d140 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
2d150 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
2d160 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
2d170 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
2d180 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
2d190 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d1a0 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
2d1b0 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
2d1c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
2d1d0 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
2d1e0 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
2d1f0 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
2d200 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
2d210 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
2d220 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
2d230 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
2d240 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
2d250 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
2d260 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
2d270 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
2d280 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
2d290 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
2d2a0 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
2d2b0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
2d2c0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
2d2d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d2e0 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
2d2f0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2d300 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
2d310 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
2d320 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
2d330 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
2d340 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
2d350 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
2d360 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
2d370 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
2d380 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
2d390 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
2d3a0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
2d3b0 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
2d3c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2d3d0 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
2d3e0 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
2d3f0 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
2d400 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
2d410 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
2d420 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
2d430 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
2d440 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
2d450 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
2d460 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
2d470 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2d480 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
2d490 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
2d4a0 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
2d4b0 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
2d4c0 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
2d4d0 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
2d4e0 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
2d4f0 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
2d500 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
2d510 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
2d520 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
2d530 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
2d540 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
2d550 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
2d560 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
2d570 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
2d580 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
2d590 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2d5a0 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
2d5b0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
2d5c0 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
2d5d0 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
2d5e0 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
2d5f0 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
2d600 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
2d610 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
2d620 2e 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51  . As many as [SQ
2d630 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f  LITE_MAX_SCHEMA_
2d640 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65  RETRY].** retrie
2d650 73 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66  s will occur bef
2d660 6f 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ore sqlite3_step
2d670 28 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20  () gives up and 
2d680 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72  returns an error
2d690 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
2d6a0 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
2d6b0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
2d6c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2d6d0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
2d6e0 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
2d6f0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
2d700 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
2d710 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
2d720 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
2d730 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
2d740 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2d750 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
2d760 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
2d770 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
2d780 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
2d790 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
2d7a0 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
2d7b0 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
2d7c0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2d7d0 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
2d7e0 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
2d7f0 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
2d800 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
2d810 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
2d820 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
2d830 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
2d840 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
2d850 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
2d860 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
2d870 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
2d880 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
2d890 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
2d8a0 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
2d8b0 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
2d8c0 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
2d8d0 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
2d8e0 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
2d8f0 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
2d900 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
2d910 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
2d920 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
2d930 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
2d940 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
2d950 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
2d960 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
2d970 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
2d980 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
2d990 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
2d9a0 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
2d9b0 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
2d9c0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
2d9d0 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
2d9e0 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
2d9f0 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
2da00 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
2da10 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
2da20 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
2da30 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
2da40 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
2da50 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2da60 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
2da70 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
2da80 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
2da90 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
2daa0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
2dab0 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
2dac0 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
2dad0 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
2dae0 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
2daf0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2db00 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
2db10 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
2db20 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2db30 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2db40 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
2db50 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2db60 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2db70 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2db80 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2db90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2dba0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
2dbb0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
2dbc0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
2dbd0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
2dbe0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
2dbf0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
2dc00 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
2dc10 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
2dc20 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2dc30 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
2dc40 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
2dc50 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
2dc60 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
2dc70 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2dc80 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2dc90 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
2dca0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2dcb0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2dcc0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
2dcd0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2dce0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2dcf0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
2dd00 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2dd10 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2dd20 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2dd30 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2dd40 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2dd50 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2dd60 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2dd70 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2dd80 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2dd90 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2dda0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2ddb0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2ddc0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2ddd0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2dde0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
2ddf0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2de00 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2de10 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2de20 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2de30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2de40 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2de50 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2de60 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2de70 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2de80 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2de90 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2dea0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2deb0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2dec0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2ded0 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
2dee0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2def0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2df00 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2df10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2df20 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2df30 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
2df40 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2df50 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2df60 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2df70 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2df80 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2df90 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2dfa0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2dfb0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2dfc0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2dfd0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2dfe0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2dff0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2e000 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2e010 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2e020 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2e030 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2e040 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2e050 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2e060 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2e070 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
2e080 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
2e090 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2e0a0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2e0b0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  The sqlite3_sql(
2e0c0 50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  P) interface ret
2e0d0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2e0e0 6f 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  o a copy of the 
2e0f0 55 54 46 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78  UTF-8.** SQL tex
2e100 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
2e110 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e120 6d 65 6e 74 5d 20 50 20 69 66 20 50 20 77 61 73  ment] P if P was
2e130 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 65  .** created by e
2e140 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2e150 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2e160 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e170 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68  16_v2()]..** ^Th
2e180 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64  e sqlite3_expand
2e190 65 64 5f 73 71 6c 28 50 29 20 69 6e 74 65 72 66  ed_sql(P) interf
2e1a0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
2e1b0 69 6e 74 65 72 20 74 6f 20 61 20 55 54 46 2d 38  inter to a UTF-8
2e1c0 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61  .** string conta
2e1d0 69 6e 69 6e 67 20 74 68 65 20 53 51 4c 20 74 65  ining the SQL te
2e1e0 78 74 20 6f 66 20 70 72 65 70 61 72 65 64 20 73  xt of prepared s
2e1f0 74 61 74 65 6d 65 6e 74 20 50 20 77 69 74 68 0a  tatement P with.
2e200 2a 2a 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  ** [bound parame
2e210 74 65 72 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a  ters] expanded..
2e220 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2e230 70 6c 65 2c 20 69 66 20 61 20 70 72 65 70 61 72  ple, if a prepar
2e240 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
2e250 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68  created using th
2e260 65 20 53 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53  e SQL.** text "S
2e270 45 4c 45 43 54 20 24 61 62 63 2c 3a 78 79 7a 22  ELECT $abc,:xyz"
2e280 20 61 6e 64 20 69 66 20 70 61 72 61 6d 65 74 65   and if paramete
2e290 72 20 24 61 62 63 20 69 73 20 62 6f 75 6e 64 20  r $abc is bound 
2e2a0 74 6f 20 69 6e 74 65 67 65 72 20 32 33 34 35 0a  to integer 2345.
2e2b0 2a 2a 20 61 6e 64 20 70 61 72 61 6d 65 74 65 72  ** and parameter
2e2c0 20 3a 78 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64   :xyz is unbound
2e2d0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 73  , then sqlite3_s
2e2e0 71 6c 28 29 20 77 69 6c 6c 20 72 65 74 75 72 6e  ql() will return
2e2f0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
2e300 20 73 74 72 69 6e 67 2c 20 22 53 45 4c 45 43 54   string, "SELECT
2e310 20 24 61 62 63 2c 3a 78 79 7a 22 20 62 75 74 20   $abc,:xyz" but 
2e320 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
2e330 5f 73 71 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72  _sql().** will r
2e340 65 74 75 72 6e 20 22 53 45 4c 45 43 54 20 32 33  eturn "SELECT 23
2e350 34 35 2c 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a  45,NULL".)^.**.*
2e360 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
2e370 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e  xpanded_sql() in
2e380 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2e390 4e 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63  NULL if insuffic
2e3a0 69 65 6e 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69  ient memory.** i
2e3b0 73 20 61 76 61 69 6c 61 62 6c 65 20 74 6f 20 68  s available to h
2e3c0 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 2c 20  old the result, 
2e3d0 6f 72 20 69 66 20 74 68 65 20 72 65 73 75 6c 74  or if the result
2e3e0 20 77 6f 75 6c 64 20 65 78 63 65 65 64 20 74 68   would exceed th
2e3f0 65 0a 2a 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d  e.** the maximum
2e400 20 73 74 72 69 6e 67 20 6c 65 6e 67 74 68 20 64   string length d
2e410 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65  etermined by the
2e420 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c   [SQLITE_LIMIT_L
2e430 45 4e 47 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ENGTH]..**.** ^T
2e440 68 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45  he [SQLITE_TRACE
2e450 5f 53 49 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d  _SIZE_LIMIT] com
2e460 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2e470 20 6c 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65   limits the size
2e480 20 6f 66 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72   of.** bound par
2e490 61 6d 65 74 65 72 20 65 78 70 61 6e 73 69 6f 6e  ameter expansion
2e4a0 73 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  s.  ^The [SQLITE
2e4b0 5f 4f 4d 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d  _OMIT_TRACE] com
2e4c0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
2e4d0 69 6f 6e 20 63 61 75 73 65 73 20 73 71 6c 69 74  ion causes sqlit
2e4e0 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2e4f0 29 20 74 6f 20 61 6c 77 61 79 73 20 72 65 74 75  ) to always retu
2e500 72 6e 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  rn NULL..**.** ^
2e510 54 68 65 20 73 74 72 69 6e 67 20 72 65 74 75 72  The string retur
2e520 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  ned by sqlite3_s
2e530 71 6c 28 50 29 20 69 73 20 6d 61 6e 61 67 65 64  ql(P) is managed
2e540 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64 20 69   by SQLite and i
2e550 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
2e560 6c 79 20 66 72 65 65 64 20 77 68 65 6e 20 74 68  ly freed when th
2e570 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
2e580 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
2e590 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e  d..** ^The strin
2e5a0 67 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  g returned by sq
2e5b0 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73  lite3_expanded_s
2e5c0 71 6c 28 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74  ql(P), on the ot
2e5d0 68 65 72 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20  her hand,.** is 
2e5e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2e5f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2e600 20 61 6e 64 20 6d 75 73 74 20 62 65 20 66 72 65   and must be fre
2e610 65 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  e by the applica
2e620 74 69 6f 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69  tion.** by passi
2e630 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
2e640 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2f 0a 53 51  3_free()]..*/.SQ
2e650 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2e660 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c  har *sqlite3_sql
2e670 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2e680 53 74 6d 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  Stmt);.SQLITE_AP
2e690 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
2e6a0 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 73 71 6c  expanded_sql(sql
2e6b0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2e6c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e6d0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
2e6e0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2e6f0 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
2e700 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a  abase.** METHOD:
2e710 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2e720 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2e730 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
2e740 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2e750 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2e760 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
2e770 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
2e780 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
2e790 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
2e7a0 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
2e7b0 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2e7c0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
2e7d0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2e7e0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2e7f0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2e800 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
2e810 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
2e820 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
2e830 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
2e840 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
2e850 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
2e860 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
2e870 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
2e880 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
2e890 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
2e8a0 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
2e8b0 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
2e8c0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
2e8d0 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
2e8e0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2e8f0 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
2e900 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
2e910 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2e920 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
2e930 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
2e940 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
2e950 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
2e960 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
2e970 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
2e980 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2e990 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
2e9a0 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2e9b0 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
2e9c0 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
2e9d0 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
2e9e0 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
2e9f0 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
2ea00 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
2ea10 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
2ea20 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
2ea30 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
2ea40 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
2ea50 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
2ea60 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
2ea70 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
2ea80 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
2ea90 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
2eaa0 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
2eab0 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
2eac0 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
2ead0 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
2eae0 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
2eaf0 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
2eb00 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
2eb10 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
2eb20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
2eb30 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
2eb40 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
2eb50 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
2eb60 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
2eb70 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
2eb80 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
2eb90 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
2eba0 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
2ebb0 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
2ebc0 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
2ebd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
2ebe0 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
2ebf0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
2ec00 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2ec10 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
2ec20 6f 6e 20 64 69 73 6b 2e 0a 2a 2a 20 5e 54 68 65  on disk..** ^The
2ec30 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2ec40 61 64 6f 6e 6c 79 28 29 20 69 6e 74 65 72 66 61  adonly() interfa
2ec50 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2ec60 66 6f 72 20 5b 42 45 47 49 4e 5d 20 73 69 6e 63  for [BEGIN] sinc
2ec70 65 0a 2a 2a 20 5b 42 45 47 49 4e 5d 20 6d 65 72  e.** [BEGIN] mer
2ec80 65 6c 79 20 73 65 74 73 20 69 6e 74 65 72 6e 61  ely sets interna
2ec90 6c 20 66 6c 61 67 73 2c 20 62 75 74 20 74 68 65  l flags, but the
2eca0 20 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 49 4d   [BEGIN|BEGIN IM
2ecb0 4d 45 44 49 41 54 45 5d 20 61 6e 64 0a 2a 2a 20  MEDIATE] and.** 
2ecc0 5b 42 45 47 49 4e 7c 42 45 47 49 4e 20 45 58 43  [BEGIN|BEGIN EXC
2ecd0 4c 55 53 49 56 45 5d 20 63 6f 6d 6d 61 6e 64 73  LUSIVE] commands
2ece0 20 64 6f 20 74 6f 75 63 68 20 74 68 65 20 64 61   do touch the da
2ecf0 74 61 62 61 73 65 20 61 6e 64 20 73 6f 0a 2a 2a  tabase and so.**
2ed00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
2ed10 61 64 6f 6e 6c 79 28 29 20 72 65 74 75 72 6e 73  adonly() returns
2ed20 20 66 61 6c 73 65 20 66 6f 72 20 74 68 6f 73 65   false for those
2ed30 20 63 6f 6d 6d 61 6e 64 73 2e 0a 2a 2f 0a 53 51   commands..*/.SQ
2ed40 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2ed50 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2ed60 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ly(sqlite3_stmt 
2ed70 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2ed80 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
2ed90 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65  ine If A Prepare
2eda0 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20  d Statement Has 
2edb0 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45  Been Reset.** ME
2edc0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2edd0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  mt.**.** ^The sq
2ede0 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2edf0 53 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  S) interface ret
2ee00 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
2ee10 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b  ero) if the.** [
2ee20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ee30 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73  nt] S has been s
2ee40 74 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20  tepped at least 
2ee50 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  once using .** [
2ee60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2ee70 20 62 75 74 20 68 61 73 20 6e 65 69 74 68 65 72   but has neither
2ee80 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69   run to completi
2ee90 6f 6e 20 28 72 65 74 75 72 6e 65 64 0a 2a 2a 20  on (returned.** 
2eea0 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 66 72  [SQLITE_DONE] fr
2eeb0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  om [sqlite3_step
2eec0 28 53 29 5d 29 20 6e 6f 72 0a 2a 2a 20 62 65 65  (S)]) nor.** bee
2eed0 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
2eee0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2eef0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2ef00 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
2ef10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ef20 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
2ef30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
2ef40 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
2ef50 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2ef60 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
2ef70 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
2ef80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ef90 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
2efa0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2efb0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
2efc0 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
2efd0 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
2efe0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2eff0 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
2f000 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
2f010 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
2f020 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
2f030 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f040 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
2f050 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
2f060 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
2f070 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
2f080 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
2f090 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
2f0a0 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
2f0b0 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
2f0c0 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
2f0d0 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
2f0e0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
2f0f0 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
2f100 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
2f110 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  en..*/.SQLITE_AP
2f120 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
2f130 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f  mt_busy(sqlite3_
2f140 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2f150 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
2f160 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
2f170 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
2f180 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
2f190 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
2f1a0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2f1b0 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
2f1c0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
2f1d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2f1e0 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
2f1f0 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
2f200 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
2f210 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
2f220 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
2f230 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
2f240 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
2f250 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
2f260 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
2f270 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
2f280 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
2f290 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
2f2a0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
2f2b0 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
2f2c0 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
2f2d0 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
2f2e0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
2f2f0 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
2f300 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
2f310 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
2f320 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
2f330 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
2f340 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
2f350 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
2f360 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
2f370 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
2f380 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
2f390 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2f3a0 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
2f3b0 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
2f3c0 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
2f3d0 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
2f3e0 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
2f3f0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
2f400 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
2f410 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 54  qlite3_value.  T
2f420 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
2f430 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74 65  alue_dup()] inte
2f440 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
2f450 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20 61  d to construct a
2f460 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63 74   new .** protect
2f470 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2f480 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74 65   from an unprote
2f490 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2f4a0 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65  ue..**.** The te
2f4b0 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20  rms "protected" 
2f4c0 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64  and "unprotected
2f4d0 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68  " refer to wheth
2f4e0 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d  er or not.** a m
2f4f0 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41  utex is held.  A
2f500 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78  n internal mutex
2f510 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70   is held for a p
2f520 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2f530 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2f540 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73   but no mutex is
2f550 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70   held for an unp
2f560 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2f570 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2f580 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
2f590 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73  compiled to be s
2f5a0 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a  ingle-threaded.*
2f5b0 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  * (with [SQLITE_
2f5c0 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e  THREADSAFE=0] an
2f5d0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
2f5e0 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65  threadsafe()] re
2f5f0 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72  turning 0).** or
2f600 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75   if SQLite is ru
2f610 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75  n in one of redu
2f620 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20  ced mutex modes 
2f630 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
2f640 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
2f650 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   or [SQLITE_CONF
2f660 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a  IG_MULTITHREAD].
2f670 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  ** then there is
2f680 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20   no distinction 
2f690 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
2f6a0 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
2f6b0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
2f6c0 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74  ue objects and t
2f6d0 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20  hey can be used 
2f6e0 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e  interchangeably.
2f6f0 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f    However,.** fo
2f700 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70  r maximum code p
2f710 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73  ortability it is
2f720 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
2f730 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  t applications.*
2f740 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65  * still make the
2f750 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2f760 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2f770 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2f780 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2f790 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65  objects even whe
2f7a0 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72  n not strictly r
2f7b0 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
2f7c0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
2f7d0 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61  e objects that a
2f7e0 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72  re passed as par
2f7f0 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65  ameters into the
2f800 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
2f810 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69  on of [applicati
2f820 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2f830 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72  unctions] are pr
2f840 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  otected..** ^The
2f850 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2f860 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
2f870 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2f880 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2f890 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a   unprotected..**
2f8a0 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   Unprotected sql
2f8b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2f8c0 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ts may only be u
2f8d0 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c  sed with.** [sql
2f8e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2f8f0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2f900 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e  3_bind_value()].
2f910 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
2f920 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71  _value_blob | sq
2f930 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
2f940 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ()] family of.**
2f950 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2f960 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71  ire protected sq
2f970 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2f980 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  cts..*/.typedef 
2f990 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
2f9a0 61 6c 75 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  alue sqlite3_val
2f9b0 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
2f9c0 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
2f9d0 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
2f9e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
2f9f0 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
2fa00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
2fa10 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
2fa20 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
2fa30 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
2fa40 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
2fa50 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
2fa60 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
2fa70 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
2fa80 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
2fa90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2faa0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
2fab0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
2fac0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2fad0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
2fae0 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
2faf0 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
2fb00 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
2fb10 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
2fb20 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
2fb30 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
2fb40 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
2fb50 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
2fb60 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
2fb70 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
2fb80 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
2fb90 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
2fba0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
2fbb0 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
2fbc0 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
2fbd0 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
2fbe0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
2fbf0 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
2fc00 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
2fc10 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
2fc20 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
2fc30 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
2fc40 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
2fc50 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
2fc60 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
2fc70 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
2fc80 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
2fc90 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
2fca0 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
2fcb0 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
2fcc0 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44  nding}.** METHOD
2fcd0 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2fce0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
2fcf0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
2fd00 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
2fd10 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2fd20 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
2fd30 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
2fd40 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
2fd50 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
2fd60 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
2fd70 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
2fd80 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
2fd90 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
2fda0 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
2fdb0 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
2fdc0 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
2fdd0 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
2fde0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
2fdf0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
2fe00 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
2fe10 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
2fe20 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
2fe30 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
2fe40 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
2fe50 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
2fe60 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
2fe70 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
2fe80 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
2fe90 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
2fea0 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
2feb0 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
2fec0 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
2fed0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2fee0 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
2fef0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
2ff00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2ff10 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
2ff20 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2ff30 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
2ff40 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
2ff50 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2ff60 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
2ff70 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
2ff80 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
2ff90 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
2ffa0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2ffb0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2ffc0 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
2ffd0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
2ffe0 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
2fff0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
30000 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
30010 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
30020 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
30030 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
30040 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
30050 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
30060 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
30070 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
30080 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
30090 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
300a0 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
300b0 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
300c0 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
300d0 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
300e0 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
300f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
30100 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
30110 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
30120 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
30130 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
30140 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
30150 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
30160 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
30170 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
30180 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
30190 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
301a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
301b0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
301c0 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
301d0 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
301e0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
301f0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
30200 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
30210 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
30220 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
30230 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
30240 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
30250 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
30260 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
30270 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e  nd_blob() is a N
30280 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
30290 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
302a0 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f  meter.** is igno
302b0 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20  red and the end 
302c0 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61  result is the sa
302d0 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69  me as sqlite3_bi
302e0 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a  nd_null()..**.**
302f0 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74   ^(In those rout
30300 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61  ines that have a
30310 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
30320 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74  , its value is t
30330 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
30340 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72  bytes in the par
30350 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63  ameter.  To be c
30360 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20  lear: the value 
30370 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
30380 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e   of <u>bytes</u>
30390 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e   in the value, n
303a0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
303b0 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a   characters.)^.*
303c0 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68  * ^If the fourth
303d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
303e0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
303f0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
30400 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73  d_text16().** is
30410 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
30420 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  the length of th
30430 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74  e string is.** t
30440 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
30450 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72  es up to the fir
30460 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
30470 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f  or..** If the fo
30480 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
30490 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  o sqlite3_bind_b
304a0 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76  lob() is negativ
304b0 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62  e, then.** the b
304c0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
304d0 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ined..** If a no
304e0 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
304f0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
30500 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
30510 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
30520 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
30530 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73 71  d_text16() or sq
30540 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36  lite3_bind_text6
30550 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74  4() then.** that
30560 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
30570 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
30580 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
30590 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
305a0 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
305b0 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
305c0 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
305d0 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
305e0 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
305f0 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
30600 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
30610 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
30620 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
30630 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
30640 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
30650 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
30660 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
30670 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
30680 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
30690 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
306a0 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
306b0 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
306c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
306d0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
306e0 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73 74   the BLOB and st
306f0 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e 74  ring binding int
30700 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61 20  erfaces.** is a 
30710 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
30720 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
30730 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
30740 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
30750 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
30760 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
30770 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
30780 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
30790 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
307a0 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
307b0 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41  e call to bind A
307c0 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66  PI fails..** ^If
307d0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
307e0 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
307f0 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
30800 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
30810 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
30820 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
30830 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
30840 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
30850 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
30860 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
30870 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
30880 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
30890 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
308a0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
308b0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
308c0 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
308d0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
308e0 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
308f0 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
30900 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
30910 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
30920 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
30930 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
30940 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
30950 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65 20  ext64() must be 
30960 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54  one of.** [SQLIT
30970 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
30980 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45  _UTF16], [SQLITE
30990 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53  _UTF16BE], or [S
309a0 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a  QLITE_UTF16LE].*
309b0 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  * to specify the
309c0 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68 65   encoding of the
309d0 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68 69   text in the thi
309e0 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 49  rd parameter.  I
309f0 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20 61  f.** the sixth a
30a00 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
30a10 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
30a20 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
30a30 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61  he.** allowed va
30a40 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  lues shown above
30a50 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78 74  , or if the text
30a60 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
30a70 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74  ferent.** from t
30a80 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63  he encoding spec
30a90 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69 78  ified by the six
30aa0 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68  th parameter, th
30ab0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  en the behavior.
30ac0 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
30ad0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30ae0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
30af0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
30b00 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
30b10 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
30b20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
30b30 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
30b40 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
30b50 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
30b60 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
30b70 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
30b80 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
30b90 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
30ba0 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
30bb0 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
30bc0 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
30bd0 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
30be0 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
30bf0 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
30c00 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
30c10 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
30c20 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
30c30 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
30c40 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
30c50 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
30c60 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
30c70 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
30c80 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
30c90 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
30ca0 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
30cb0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
30cc0 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
30cd0 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
30ce0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30cf0 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
30d00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
30d10 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
30d20 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
30d30 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
30d40 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
30d50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
30d60 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
30d70 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
30d80 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
30d90 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
30da0 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
30db0 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
30dc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30dd0 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
30de0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
30df0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
30e00 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
30e10 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
30e20 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
30e30 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
30e40 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
30e50 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
30e60 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
30e70 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
30e80 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
30e90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
30ea0 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
30eb0 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
30ec0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
30ed0 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
30ee0 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
30ef0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
30f00 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42  ** ^[SQLITE_TOOB
30f10 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74  IG] might be ret
30f20 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69 7a  urned if the siz
30f30 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f 72  e of a string or
30f40 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73   BLOB.** exceeds
30f50 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20   limits imposed 
30f60 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
30f70 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
30f80 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20  _LENGTH]) or.** 
30f90 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47  [SQLITE_MAX_LENG
30fa0 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  TH]..** ^[SQLITE
30fb0 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
30fc0 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
30fd0 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
30fe0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
30ff0 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
31000 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
31010 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
31020 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
31030 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
31040 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
31050 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
31060 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
31070 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
31080 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
31090 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
310a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
310b0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
310c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
310d0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
310e0 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
310f0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
31100 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
31110 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74  ind_blob64(sqlit
31120 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
31130 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69  onst void*, sqli
31140 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20  te3_uint64,.    
31150 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31160 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64      void(*)(void
31170 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
31180 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
31190 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
311a0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
311b0 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  le);.SQLITE_API 
311c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
311d0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
311e0 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53  t*, int, int);.S
311f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
31200 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
31210 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31220 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
31230 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
31240 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
31250 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
31260 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  mt*, int);.SQLIT
31270 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
31280 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
31290 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 2c 63 6f  te3_stmt*,int,co
312a0 6e 73 74 20 63 68 61 72 2a 2c 69 6e 74 2c 76 6f  nst char*,int,vo
312b0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
312c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
312d0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
312e0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
312f0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
31300 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
31310 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
31320 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
31330 62 69 6e 64 5f 74 65 78 74 36 34 28 73 71 6c 69  bind_text64(sqli
31340 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
31350 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
31360 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
31370 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31380 20 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f        void(*)(vo
31390 69 64 2a 29 2c 20 75 6e 73 69 67 6e 65 64 20 63  id*), unsigned c
313a0 68 61 72 20 65 6e 63 6f 64 69 6e 67 29 3b 0a 53  har encoding);.S
313b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
313c0 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
313d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
313e0 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
313f0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
31400 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
31410 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
31420 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31430 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 53 51 4c  int, int n);.SQL
31440 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
31450 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
31460 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  b64(sqlite3_stmt
31470 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
31480 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a 20  uint64);../*.** 
31490 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
314a0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
314b0 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  rs.** METHOD: sq
314c0 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
314d0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
314e0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
314f0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
31500 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
31510 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
31520 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
31530 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
31540 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
31550 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
31560 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
31570 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
31580 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
31590 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
315a0 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
315b0 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
315c0 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
315d0 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
315e0 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
315f0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
31600 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
31610 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
31620 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
31630 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
31640 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
31650 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
31660 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
31670 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
31680 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
31690 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
316a0 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
316b0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
316c0 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
316d0 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
316e0 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
316f0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
31700 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
31710 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
31720 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
31730 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
31740 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
31750 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
31760 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
31770 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
31780 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
31790 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
317a0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
317b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
317c0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
317d0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st Parameter.** 
317e0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
317f0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
31800 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
31810 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
31820 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
31830 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
31840 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
31850 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
31860 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
31870 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
31880 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
31890 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
318a0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
318b0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
318c0 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
318d0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
318e0 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
318f0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
31900 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
31910 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
31920 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
31930 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
31940 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
31950 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
31960 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
31970 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
31980 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
31990 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
319a0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
319b0 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
319c0 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
319d0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
319e0 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
319f0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
31a00 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
31a10 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
31a20 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
31a30 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
31a40 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
31a50 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
31a60 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
31a70 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
31a80 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
31a90 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
31aa0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
31ab0 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
31ac0 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
31ad0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
31ae0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
31af0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
31b00 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
31b10 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
31b20 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
31b30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
31b40 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
31b50 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
31b60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
31b70 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
31b80 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
31b90 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
31ba0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
31bb0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
31bc0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
31bd0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
31be0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
31bf0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
31c00 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
31c10 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
31c20 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
31c30 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
31c40 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
31c50 6d 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  me.** METHOD: sq
31c60 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
31c70 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
31c80 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
31c90 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
31ca0 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
31cb0 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
31cc0 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
31cd0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
31ce0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
31cf0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
31d00 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
31d10 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
31d20 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
31d30 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
31d40 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
31d50 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
31d60 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
31d70 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
31d80 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
31d90 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
31da0 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
31db0 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
31dc0 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
31dd0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
31de0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
31df0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
31e00 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
31e10 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
31e20 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
31e30 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
31e40 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
31e50 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
31e60 65 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  e()]..*/.SQLITE_
31e70 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
31e80 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
31e90 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndex(sqlite3_stm
31ea0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  t*, const char *
31eb0 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  zName);../*.** C
31ec0 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
31ed0 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41  ll Bindings On A
31ee0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
31ef0 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
31f00 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
31f10 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74  * ^Contrary to t
31f20 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20  he intuition of 
31f30 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72  many, [sqlite3_r
31f40 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74  eset()] does not
31f50 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73   reset.** the [s
31f60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
31f70 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20   | bindings] on 
31f80 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
31f90 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20  ement]..** ^Use 
31fa0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20  this routine to 
31fb0 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70  reset all host p
31fc0 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c  arameters to NUL
31fd0 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  L..*/.SQLITE_API
31fe0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 65   int sqlite3_cle
31ff0 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69  ar_bindings(sqli
32000 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
32010 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
32020 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49  ber Of Columns I
32030 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a  n A Result Set.*
32040 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
32050 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  3_stmt.**.** ^Re
32060 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
32070 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
32080 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
32090 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
320a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
320b0 65 6e 74 5d 2e 20 5e 49 66 20 74 68 69 73 20 72  ent]. ^If this r
320c0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
320d0 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
320e0 20 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73   .** [prepared s
320f0 74 61 74 65 6d 65 6e 74 5d 20 72 65 74 75 72 6e  tatement] return
32100 73 20 6e 6f 20 64 61 74 61 20 28 66 6f 72 20 65  s no data (for e
32110 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
32120 45 5d 29 2e 0a 2a 2a 20 5e 48 6f 77 65 76 65 72  E])..** ^However
32130 2c 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 74  , just because t
32140 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
32150 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65 20 6e  rns a positive n
32160 75 6d 62 65 72 20 64 6f 65 73 20 6e 6f 74 0a 2a  umber does not.*
32170 2a 20 6d 65 61 6e 20 74 68 61 74 20 6f 6e 65 20  * mean that one 
32180 6f 72 20 6d 6f 72 65 20 72 6f 77 73 20 6f 66 20  or more rows of 
32190 64 61 74 61 20 77 69 6c 6c 20 62 65 20 72 65 74  data will be ret
321a0 75 72 6e 65 64 2e 20 20 5e 41 20 53 45 4c 45 43  urned.  ^A SELEC
321b0 54 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  T statement.** w
321c0 69 6c 6c 20 61 6c 77 61 79 73 20 68 61 76 65 20  ill always have 
321d0 61 20 70 6f 73 69 74 69 76 65 20 73 71 6c 69 74  a positive sqlit
321e0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
321f0 29 20 62 75 74 20 64 65 70 65 6e 64 69 6e 67 20  ) but depending 
32200 6f 6e 20 74 68 65 0a 2a 2a 20 57 48 45 52 45 20  on the.** WHERE 
32210 63 6c 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e  clause constrain
32220 74 73 20 61 6e 64 20 74 68 65 20 74 61 62 6c 65  ts and the table
32230 20 63 6f 6e 74 65 6e 74 2c 20 69 74 20 6d 69 67   content, it mig
32240 68 74 20 72 65 74 75 72 6e 20 6e 6f 20 72 6f 77  ht return no row
32250 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
32260 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
32270 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c  _count()].*/.SQL
32280 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
32290 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
322a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
322b0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
322c0 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e  PI3REF: Column N
322d0 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74  ames In A Result
322e0 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   Set.** METHOD: 
322f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
32300 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
32310 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  es return the na
32320 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61  me assigned to a
32330 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75   particular colu
32340 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73  mn.** in the res
32350 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
32360 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
32370 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63    ^The sqlite3_c
32380 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20  olumn_name().** 
32390 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
323a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
323b0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
323c0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
323d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
323e0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74  umn_name16() ret
323f0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
32400 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
32410 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
32420 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73  ring.  ^The firs
32430 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  t parameter is t
32440 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
32450 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20  tement].** that 
32460 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b  implements the [
32470 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
32480 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  t. ^The second p
32490 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a  arameter is the.
324a0 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  ** column number
324b0 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  .  ^The leftmost
324c0 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65   column is numbe
324d0 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r 0..**.** ^The 
324e0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
324f0 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64  pointer is valid
32500 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68   until either th
32510 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
32520 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73  ement].** is des
32530 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
32540 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f  e3_finalize()] o
32550 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74  r until the stat
32560 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74  ement is automat
32570 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70  ically.** reprep
32580 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ared by the firs
32590 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
325a0 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61  e3_step()] for a
325b0 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a   particular run.
325c0 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  ** or until the 
325d0 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  next call to.** 
325e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
325f0 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ame() or sqlite3
32600 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29  _column_name16()
32610 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c   on the same col
32620 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73  umn..**.** ^If s
32630 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
32640 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65  fails during the
32650 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65   processing of e
32660 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a  ither routine.**
32670 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75   (for example du
32680 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f  ring a conversio
32690 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20  n from UTF-8 to 
326a0 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a  UTF-16) then a.*
326b0 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  * NULL pointer i
326c0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
326d0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61  * ^The name of a
326e0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
326f0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
32700 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66  he "AS" clause f
32710 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d  or.** that colum
32720 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61  n, if there is a
32730 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66  n AS clause.  If
32740 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20   there is no AS 
32750 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74  clause.** then t
32760 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63  he name of the c
32770 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69  olumn is unspeci
32780 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61  fied and may cha
32790 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20  nge from.** one 
327a0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
327b0 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a  e to the next..*
327c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
327d0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
327e0 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c  _column_name(sql
327f0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
32800 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  N);.SQLITE_API c
32810 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
32820 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
32830 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
32840 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int N);../*.** C
32850 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65 20  API3REF: Source 
32860 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75 65  Of Data In A Que
32870 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54  ry Result.** MET
32880 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
32890 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
328a0 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
328b0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
328c0 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
328d0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
328e0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
328f0 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
32900 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
32910 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
32920 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
32930 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
32940 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
32950 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
32960 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
32970 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
32980 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
32990 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
329a0 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
329b0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
329c0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
329d0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
329e0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
329f0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
32a00 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
32a10 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
32a20 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
32a30 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
32a40 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
32a50 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
32a60 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
32a70 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
32a80 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
32a90 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
32aa0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
32ab0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
32ac0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
32ad0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
32ae0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
32af0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
32b00 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
32b10 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
32b20 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
32b30 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
32b40 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
32b50 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
32b60 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
32b70 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
32b80 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
32b90 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
32ba0 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
32bb0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
32bc0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
32bd0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
32be0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
32bf0 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
32c00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
32c10 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
32c20 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
32c30 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
32c40 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
32c50 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
32c60 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
32c70 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
32c80 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
32c90 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
32ca0 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
32cb0 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
32cc0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
32cd0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
32ce0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
32cf0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
32d00 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
32d10 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
32d20 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
32d30 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
32d40 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
32d50 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
32d60 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
32d70 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
32d80 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
32d90 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
32da0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
32db0 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
32dc0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
32dd0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
32de0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
32df0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
32e00 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
32e10 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
32e20 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
32e30 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
32e40 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
32e50 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
32e60 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
32e70 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
32e80 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
32e90 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
32ea0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
32eb0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
32ec0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
32ed0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
32ee0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
32ef0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
32f00 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
32f10 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
32f20 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
32f30 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
32f40 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
32f50 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
32f60 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
32f70 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
32f80 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
32f90 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
32fa0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
32fb0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
32fc0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
32fd0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
32fe0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
32ff0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
33000 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
33010 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
33020 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
33030 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
33040 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
33050 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
33060 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
33070 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33080 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
33090 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
330a0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
330b0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
330c0 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
330d0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
330e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
330f0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71  database_name(sq
33100 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
33110 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
33120 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
33130 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
33140 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
33150 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
33160 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
33170 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
33180 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
33190 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
331a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
331b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
331c0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
331d0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
331e0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
331f0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
33200 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72  qlite3_column_or
33210 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65  igin_name(sqlite
33220 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
33230 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
33240 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
33250 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31  umn_origin_name1
33260 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
33270 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
33280 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20  I3REF: Declared 
33290 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75  Datatype Of A Qu
332a0 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45  ery Result.** ME
332b0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
332c0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  mt.**.** ^(The f
332d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
332e0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
332f0 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20  atement]..** If 
33300 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69  this statement i
33310 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  s a [SELECT] sta
33320 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e  tement and the N
33330 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
33340 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73  .** returned res
33350 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74 20  ult set of that 
33360 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61  [SELECT] is a ta
33370 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20  ble column (not 
33380 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
33390 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74 68   or subquery) th
333a0 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  en the declared 
333b0 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c  type of the tabl
333c0 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72  e.** column is r
333d0 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20  eturned.)^  ^If 
333e0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
333f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
33400 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73   is an.** expres
33410 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
33420 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f  , then a NULL po
33430 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
33440 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  d..** ^The retur
33450 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c  ned string is al
33460 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64  ways UTF-8 encod
33470 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20  ed..**.** ^(For 
33480 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74  example, given t
33490 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
334a0 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45  ma:.**.** CREATE
334b0 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41 52   TABLE t1(c1 VAR
334c0 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64  IANT);.**.** and
334d0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73   the following s
334e0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
334f0 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53  ompiled:.**.** S
33500 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31  ELECT c1 + 1, c1
33510 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20   FROM t1;.**.** 
33520 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75  this routine wou
33530 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73 74  ld return the st
33540 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66  ring "VARIANT" f
33550 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65  or the second re
33560 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28  sult.** column (
33570 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c  i==1), and a NUL
33580 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  L pointer for th
33590 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20 63  e first result c
335a0 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a  olumn (i==0).)^.
335b0 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73  **.** ^SQLite us
335c0 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74  es dynamic run-t
335d0 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f  ime typing.  ^So
335e0 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61 20   just because a 
335f0 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63  column.** is dec
33600 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e  lared to contain
33610 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74 79   a particular ty
33620 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e  pe does not mean
33630 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74   that the.** dat
33640 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74  a stored in that
33650 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68   column is of th
33660 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e  e declared type.
33670 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73    SQLite is.** s
33680 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62  trongly typed, b
33690 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69 73  ut the typing is
336a0 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61   dynamic not sta
336b0 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69  tic.  ^Type.** i
336c0 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  s associated wit
336d0 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c  h individual val
336e0 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68  ues, not with th
336f0 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20  e containers.** 
33700 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f  used to hold tho
33710 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51  se values..*/.SQ
33720 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
33730 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
33740 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c  umn_decltype(sql
33750 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
33760 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
33770 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
33780 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
33790 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
337a0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
337b0 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
337c0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
337d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
337e0 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41  te3_stmt.**.** A
337f0 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64  fter a [prepared
33800 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20   statement] has 
33810 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73  been prepared us
33820 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73  ing either.** [s
33830 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
33840 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
33850 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
33860 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c   or one of the l
33870 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
33880 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ces [sqlite3_pre
33890 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  pare()] or [sqli
338a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
338b0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a  , this function.
338c0 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ** must be calle
338d0 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  d one or more ti
338e0 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20  mes to evaluate 
338f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  the statement..*
33900 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73  *.** The details
33910 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72   of the behavior
33920 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
33930 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65  step() interface
33940 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68   depend.** on wh
33950 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d  ether the statem
33960 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64  ent was prepared
33970 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72   using the newer
33980 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a   "v2" interface.
33990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
339a0 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
339b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
339c0 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c  _v2()] or the ol
339d0 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  der legacy.** in
339e0 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33  terface [sqlite3
339f0 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20  _prepare()] and 
33a00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
33a10 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20  16()].  The use 
33a20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76  of the.** new "v
33a30 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  2" interface is 
33a40 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
33a50 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
33a60 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a   but the legacy.
33a70 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c  ** interface wil
33a80 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  l continue to be
33a90 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a   supported..**.*
33aa0 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79  * ^In the legacy
33ab0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
33ac0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c  return value wil
33ad0 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c  l be either [SQL
33ae0 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53  ITE_BUSY],.** [S
33af0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51  QLITE_DONE], [SQ
33b00 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49  LITE_ROW], [SQLI
33b10 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53  TE_ERROR], or [S
33b20 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a  QLITE_MISUSE]..*
33b30 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22  * ^With the "v2"
33b40 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20   interface, any 
33b50 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65  of the other [re
33b60 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a  sult codes] or.*
33b70 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
33b80 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20  lt codes] might 
33b90 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77  be returned as w
33ba0 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ell..**.** ^[SQL
33bb0 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20  ITE_BUSY] means 
33bc0 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
33bd0 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61  e engine was una
33be0 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74  ble to acquire t
33bf0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c  he.** database l
33c00 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f  ocks it needs to
33c10 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49   do its job.  ^I
33c20 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  f the statement 
33c30 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a  is a [COMMIT].**
33c40 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69   or occurs outsi
33c50 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69  de of an explici
33c60 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
33c70 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72  hen you can retr
33c80 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  y the.** stateme
33c90 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74  nt.  If the stat
33ca0 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b  ement is not a [
33cb0 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75  COMMIT] and occu
33cc0 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20  rs within an.** 
33cd0 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
33ce0 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68  tion then you sh
33cf0 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68  ould rollback th
33d00 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
33d10 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69  fore.** continui
33d20 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ng..**.** ^[SQLI
33d30 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74  TE_DONE] means t
33d40 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hat the statemen
33d50 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65  t has finished e
33d60 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63  xecuting.** succ
33d70 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74  essfully.  sqlit
33d80 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
33d90 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
33da0 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72  gain on this vir
33db0 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
33dc0 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61  without first ca
33dd0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
33de0 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74  eset()] to reset
33df0 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20   the virtual.** 
33e00 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20  machine back to 
33e10 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
33e20 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  e..**.** ^If the
33e30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62   SQL statement b
33e40 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65  eing executed re
33e50 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20  turns any data, 
33e60 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  then [SQLITE_ROW
33e70 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  ].** is returned
33e80 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77   each time a new
33e90 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20   row of data is 
33ea0 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73  ready for proces
33eb0 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63  sing by the.** c
33ec0 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65  aller. The value
33ed0 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65  s may be accesse
33ee0 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c  d using the [col
33ef0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
33f00 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65  ions]..** sqlite
33f10 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c  3_step() is call
33f20 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72  ed again to retr
33f30 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f  ieve the next ro
33f40 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a  w of data..**.**
33f50 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d   ^[SQLITE_ERROR]
33f60 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75   means that a ru
33f70 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75  n-time error (su
33f80 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69  ch as a constrai
33f90 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29  nt.** violation)
33fa0 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20   has occurred.  
33fb0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73  sqlite3_step() s
33fc0 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c  hould not be cal
33fd0 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20  led again on.** 
33fe0 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66  the VM. More inf
33ff0 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20  ormation may be 
34000 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67  found by calling
34010 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
34020 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  ()]..** ^With th
34030 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
34040 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69  ce, a more speci
34050 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28  fic error code (
34060 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  for example,.** 
34070 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
34080 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45  T], [SQLITE_SCHE
34090 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52  MA], [SQLITE_COR
340a0 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f  RUPT], and so fo
340b0 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f  rth).** can be o
340c0 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69  btained by calli
340d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
340e0 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b  t()] on the.** [
340f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34100 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76  nt].  ^In the "v
34110 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a  2" interface,.**
34120 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
34130 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  ic error code is
34140 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
34150 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74  ly by sqlite3_st
34160 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c  ep()..**.** [SQL
34170 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e  ITE_MISUSE] mean
34180 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20  s that the this 
34190 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c  routine was call
341a0 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65  ed inappropriate
341b0 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69  ly..** Perhaps i
341c0 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20  t was called on 
341d0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
341e0 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a  ement] that has.
341f0 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20  ** already been 
34200 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
34210 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f  e | finalized] o
34220 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61  r on one that ha
34230 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  d.** previously 
34240 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
34250 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49  _ERROR] or [SQLI
34260 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74  TE_DONE].  Or it
34270 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65   could.** be the
34280 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73   case that the s
34290 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
342a0 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67  nection is being
342b0 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a   used by two or.
342c0 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  ** more threads 
342d0 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65  at the same mome
342e0 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a  nt in time..**.*
342f0 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f  * For all versio
34300 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20  ns of SQLite up 
34310 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67  to and including
34320 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c   3.6.23.1, a cal
34330 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
34340 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65  _reset()] was re
34350 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c  quired after sql
34360 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75  ite3_step() retu
34370 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a  rned anything.**
34380 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
34390 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20  ITE_ROW] before 
343a0 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69  any subsequent i
343b0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  nvocation of.** 
343c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
343d0 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65   Failure to rese
343e0 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  t the prepared s
343f0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a  tatement using .
34400 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
34410 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c  t()] would resul
34420 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f  t in an [SQLITE_
34430 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66  MISUSE] return f
34440 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  rom.** sqlite3_s
34450 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65  tep().  But afte
34460 72 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32  r [version 3.6.2
34470 33 2e 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e  3.1] ([dateof:3.
34480 36 2e 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69  6.23.1],.** sqli
34490 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
344a0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
344b0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
344c0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
344d0 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
344e0 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
344f0 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
34500 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
34510 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
34520 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
34530 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
34540 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
34550 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
34560 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
34570 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
34580 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
34590 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
345a0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
345b0 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
345c0 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
345d0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
345e0 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
345f0 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
34600 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
34610 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
34620 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
34630 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
34640 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
34650 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
34660 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
34670 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
34680 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
34690 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
346a0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
346b0 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
346c0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
346d0 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
346e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
346f0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
34700 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
34710 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
34720 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
34730 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
34740 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
34750 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
34760 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
34770 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
34780 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
34790 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
347a0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
347b0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
347c0 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
347d0 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
347e0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
347f0 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
34800 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
34810 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
34820 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
34830 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
34840 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
34850 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
34860 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
34870 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
34880 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
34890 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
348a0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
348b0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
348c0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
348d0 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
348e0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
348f0 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
34900 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
34910 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 65   int sqlite3_ste
34920 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  p(sqlite3_stmt*)
34930 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34940 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  F: Number of col
34950 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c 74  umns in a result
34960 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20   set.** METHOD: 
34970 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
34980 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34990 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
349a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
349b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
349c0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
349d0 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
349e0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
349f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
34a00 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
34a10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
34a20 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
34a30 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
34a40 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
34a50 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
34a60 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
34a70 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
34a80 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
34a90 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
34aa0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
34ab0 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
34ac0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
34ad0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
34ae0 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
34af0 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
34b00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
34b10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
34b20 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
34b30 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
34b40 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
34b50 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
34b60 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
34b70 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  rned [SQLITE_DON
34b80 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  E].  ^The sqlite
34b90 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a  3_data_count(P).
34ba0 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e  ** will return n
34bb0 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69  on-zero if previ
34bc0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ous call to [sql
34bd0 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
34be0 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
34bf0 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69  E_ROW], except i
34c00 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68  n the case of th
34c10 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d  e [PRAGMA increm
34c20 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a  ental_vacuum].**
34c30 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73   where it always
34c40 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69   returns zero si
34c50 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66  nce each step of
34c60 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70   that multi-step
34c70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72  .** pragma retur
34c80 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ns 0 columns of 
34c90 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  data..**.** See 
34ca0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
34cb0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
34cc0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
34cd0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
34ce0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
34cf0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
34d00 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
34d10 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
34d20 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
34d30 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
34d40 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
34d50 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
34d60 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
34d70 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
34d80 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
34d90 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
34da0 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
34db0 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
34dc0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
34dd0 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
34de0 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
34df0 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
34e00 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
34e10 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
34e20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
34e30 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
34e40 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
34e50 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
34e60 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
34e70 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
34e80 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
34e90 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
34ea0 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
34eb0 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
34ec0 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
34ed0 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
34ee0 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
34ef0 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
34f00 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
34f10 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
34f20 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
34f30 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
34f40 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
34f50 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
34f60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
34f70 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
34f80 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
34f90 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
34fa0 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
34fb0 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
34fc0 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
34fd0 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
34fe0 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
34ff0 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
35000 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
35010 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
35020 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
35030 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
35040 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
35050 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
35060 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
35070 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
35080 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
35090 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
350a0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
350b0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
350c0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
350d0 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
350e0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
350f0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
35100 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
35110 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
35120 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
35130 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
35140 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
35150 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
35160 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
35170 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
35180 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
35190 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
351a0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
351b0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
351c0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
351d0 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
351e0 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
351f0 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
35200 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
35210 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
35220 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
35230 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
35240 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
35250 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
35260 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
35270 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
35280 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
35290 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
352a0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
352b0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
352c0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
352d0 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
352e0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
352f0 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
35300 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
35310 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
35320 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
35330 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
35340 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
35350 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
35360 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
35370 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
35380 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
35390 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
353a0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
353b0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
353c0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
353d0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
353e0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
353f0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
35400 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
35410 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
35420 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
35430 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
35440 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
35450 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
35460 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
35470 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
35480 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
35490 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
354a0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
354b0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
354c0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
354d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
354e0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
354f0 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
35500 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
35510 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
35520 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
35530 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
35540 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
35550 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
35560 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
35570 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
35580 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
35590 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
355a0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
355b0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
355c0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
355d0 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
355e0 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
355f0 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
35600 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
35610 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
35620 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
35630 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
35640 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
35650 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
35660 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
35670 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
35680 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
35690 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
356a0 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
356b0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
356c0 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
356d0 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
356e0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
356f0 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
35700 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
35710 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
35720 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
35730 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
35740 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
35750 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
35760 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
35770 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
35780 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
35790 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
357a0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
357b0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
357c0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
357d0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
357e0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
357f0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
35800 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
35810 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
35820 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
35830 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
35840 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
35850 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
35860 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
35870 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
35880 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
35890 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
358a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
358b0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
358c0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
358d0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
358e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
358f0 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
35900 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
35910 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
35920 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
35930 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
35940 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
35950 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
35960 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
35970 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
35980 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
35990 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
359a0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
359b0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
359c0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
359d0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
359e0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
359f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
35a00 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
35a10 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
35a20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
35a30 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
35a40 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
35a50 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
35a60 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
35a70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
35a80 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
35a90 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
35aa0 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
35ab0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
35ac0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
35ad0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
35ae0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
35af0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
35b00 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
35b10 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
35b20 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
35b30 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
35b40 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
35b50 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
35b60 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
35b70 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
35b80 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
35b90 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
35ba0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
35bb0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
35bc0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
35bd0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
35be0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
35bf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
35c00 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
35c10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
35c20 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
35c30 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
35c40 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
35c50 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
35c60 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
35c70 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
35c80 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
35c90 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
35ca0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
35cb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
35cc0 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
35cd0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
35ce0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
35cf0 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
35d00 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
35d10 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
35d20 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
35d30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
35d40 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
35d50 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
35d60 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
35d70 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
35d80 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
35d90 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
35da0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
35db0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
35dc0 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
35dd0 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
35de0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
35df0 0a 2a 2a 20 3c 62 3e 57 61 72 6e 69 6e 67 3a 3c  .** <b>Warning:<
35e00 2f 62 3e 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  /b> ^The object 
35e10 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
35e20 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
35e30 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
35e40 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
35e50 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
35e60 2e 20 20 49 6e 20 61 20 6d 75 6c 74 69 74 68 72  .  In a multithr
35e70 65 61 64 65 64 20 65 6e 76 69 72 6f 6e 6d 65 6e  eaded environmen
35e80 74 2c 0a 2a 2a 20 61 6e 20 75 6e 70 72 6f 74 65  t,.** an unprote
35e90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
35ea0 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 6f 6e  ue object may on
35eb0 6c 79 20 62 65 20 75 73 65 64 20 73 61 66 65 6c  ly be used safel
35ec0 79 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  y with.** [sqlit
35ed0 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
35ee0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
35ef0 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  sult_value()]..*
35f00 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74  * If the [unprot
35f10 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
35f20 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  lue] object retu
35f30 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
35f40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
35f50 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61  ()] is used in a
35f60 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e  ny other way, in
35f70 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a  cluding calls.**
35f80 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b   to routines lik
35f90 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
35fa0 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  _int()], [sqlite
35fb0 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
35fc0 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
35fd0 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20  value_bytes()], 
35fe0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
35ff0 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 0a  not threadsafe..
36000 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
36010 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20  ines attempt to 
36020 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
36030 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69  e where appropri
36040 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78  ate.  ^For.** ex
36050 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e  ample, if the in
36060 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
36070 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61  ation is FLOAT a
36080 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74  nd a text result
36090 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64  .** is requested
360a0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  , [sqlite3_snpri
360b0 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69  ntf()] is used i
360c0 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72  nternally to per
360d0 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76  form the.** conv
360e0 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63  ersion automatic
360f0 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c  ally.  ^(The fol
36100 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74  lowing table det
36110 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73  ails the convers
36120 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ions.** that are
36130 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20   applied:.**.** 
36140 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20  <blockquote>.** 
36150 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
36160 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49  ">.** <tr><th> I
36170 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20  nternal<br>Type 
36180 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62  <th> Requested<b
36190 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e  r>Type <th>  Con
361a0 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74  version.**.** <t
361b0 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
361c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
361d0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a  td> Result is 0.
361e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
361f0 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  L    <td>  FLOAT
36200 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
36210 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74  is 0.0.** <tr><t
36220 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
36230 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20     TEXT    <td> 
36240 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
36250 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
36260 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
36270 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
36280 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55  > Result is a NU
36290 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74  LL pointer.** <t
362a0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
362b0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
362c0 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d  td> Convert from
362d0 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61   integer to floa
362e0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  t.** <tr><td> IN
362f0 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45  TEGER  <td>   TE
36300 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
36310 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
36320 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  e integer.** <tr
36330 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
36340 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
36350 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47  d> Same as INTEG
36360 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  ER->TEXT.** <tr>
36370 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
36380 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
36390 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
363a0 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
363b0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
363c0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
363d0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
363e0 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
363f0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
36400 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
36410 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f  d> [CAST] to BLO
36420 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  B.** <tr><td>  T
36430 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
36440 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
36450 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
36460 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
36470 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
36480 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
36490 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  REAL.** <tr><td>
364a0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
364b0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
364c0 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
364d0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
364e0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
364f0 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
36500 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
36510 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c  BLOB    <td>  FL
36520 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
36530 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
36540 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
36550 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
36560 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
36570 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
36580 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
36590 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
365a0 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  )^.**.** Note th
365b0 61 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e  at when type con
365c0 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20  versions occur, 
365d0 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
365e0 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61  d by prior.** ca
365f0 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
36600 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71  olumn_blob(), sq
36610 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
36620 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73  t(), and/or.** s
36630 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
36640 78 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e  xt16() may be in
36650 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79  validated..** Ty
36660 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61  pe conversions a
36670 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c  nd pointer inval
36680 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f  idations might o
36690 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ccur.** in the f
366a0 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a  ollowing cases:.
366b0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
366c0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
366d0 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42  ontent is a BLOB
366e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
366f0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a  umn_text() or.**
36700 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
36710 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73  lumn_text16() is
36720 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f   called.  A zero
36730 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68  -terminator migh
36740 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74  t.**      need t
36750 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68  o be added to th
36760 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a  e string.</li>.*
36770 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
36780 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
36790 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c  F-8 text and sql
367a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
367b0 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  s16() or.**     
367c0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
367d0 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
367e0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
367f0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
36800 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
36810 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  F-16.</li>.** <l
36820 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
36830 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36  ontent is UTF-16
36840 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
36850 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
36860 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
36870 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
36880 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
36890 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
368a0 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
368b0 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c      to UTF-8.</l
368c0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
368d0 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62  * ^Conversions b
368e0 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20  etween UTF-16be 
368f0 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65  and UTF-16le are
36900 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20   always done in 
36910 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20  place and do.** 
36920 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61  not invalidate a
36930 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20   prior pointer, 
36940 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65  though of course
36950 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
36960 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  the buffer.** th
36970 61 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69  at the prior poi
36980 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20  nter references 
36990 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d  will have been m
369a0 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20  odified.  Other 
369b0 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76  kinds.** of conv
369c0 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20  ersion are done 
369d0 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74  in place when it
369e0 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75   is possible, bu
369f0 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79  t sometimes they
36a00 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73  .** are not poss
36a10 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73  ible and in thos
36a20 65 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f  e cases prior po
36a30 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c  inters are inval
36a40 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  idated..**.** Th
36a50 65 20 73 61 66 65 73 74 20 70 6f 6c 69 63 79 20  e safest policy 
36a60 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
36a70 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
36a80 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
36a90 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
36aa0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
36ab0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
36ac0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
36ad0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
36ae0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
36af0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
36b00 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
36b10 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
36b20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
36b30 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
36b40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
36b50 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
36b60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36b70 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
36b80 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
36b90 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
36ba0 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
36bb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
36bc0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
36bd0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
36be0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
36bf0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
36c00 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
36c10 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
36c20 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
36c30 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
36c40 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
36c50 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
36c60 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
36c70 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
36c80 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
36c90 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
36ca0 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
36cb0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
36cc0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
36cd0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
36ce0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
36cf0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
36d00 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
36d10 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
36d20 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
36d30 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
36d40 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
36d50 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
36d60 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
36d70 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
36d80 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
36d90 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
36da0 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
36db0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
36dc0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
36dd0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
36de0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
36df0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
36e00 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
36e10 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
36e20 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
36e30 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
36e40 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
36e50 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
36e60 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e 20 70 61 73 73  em>not</em> pass
36e70 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
36e80 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
36e90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
36ea0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
36eb0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
36ec0 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
36ed0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
36ee0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
36ef0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
36f00 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
36f10 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
36f20 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
36f30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
36f40 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
36f50 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
36f60 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
36f70 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
36f80 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
36f90 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
36fa0 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
36fb0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
36fc0 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
36fd0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
36fe0 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
36ff0 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
37000 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c  NOMEM].)^.*/.SQL
37010 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
37020 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
37030 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
37040 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
37050 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
37060 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37070 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
37080 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
37090 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
370a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
370b0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
370c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
370d0 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c  SQLITE_API doubl
370e0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
370f0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
37100 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
37110 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
37120 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
37130 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
37140 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
37150 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
37160 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
37170 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
37180 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
37190 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
371a0 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20   const unsigned 
371b0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
371c0 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
371d0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
371e0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  l);.SQLITE_API c
371f0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
37200 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
37210 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
37220 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
37230 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
37240 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
37250 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
37260 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
37270 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  PI sqlite3_value
37280 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
37290 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
372a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
372b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
372c0 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
372d0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
372e0 62 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43  bject.** DESTRUC
372f0 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
37300 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
37310 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
37320 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
37330 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b  ed to delete a [
37340 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37350 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  nt]..** ^If the 
37360 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c  most recent eval
37370 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74  uation of the st
37380 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65  atement encounte
37390 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  red no errors.**
373a0 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65   or if the state
373b0 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65  ment is never be
373c0 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68  en evaluated, th
373d0 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  en sqlite3_final
373e0 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  ize() returns.**
373f0 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66   SQLITE_OK.  ^If
37400 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
37410 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73   evaluation of s
37420 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65  tatement S faile
37430 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  d, then.** sqlit
37440 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
37450 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f  eturns the appro
37460 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
37470 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  de] or.** [exten
37480 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ded error code].
37490 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
374a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
374b0 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63  routine can be c
374c0 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69  alled at any poi
374d0 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65  nt during.** the
374e0 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b   life cycle of [
374f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37500 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65  nt] S:.** before
37510 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20   statement S is 
37520 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20  ever evaluated, 
37530 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20  after.** one or 
37540 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73  more calls to [s
37550 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
37560 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61   or after any ca
37570 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ll.** to [sqlite
37580 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64  3_step()] regard
37590 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
375a0 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65  or not the state
375b0 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70  ment has.** comp
375c0 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e  leted execution.
375d0 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67  .**.** ^Invoking
375e0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
375f0 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f  e() on a NULL po
37600 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c  inter is a harml
37610 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a  ess no-op..**.**
37620 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
37630 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65   must finalize e
37640 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73  very [prepared s
37650 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64  tatement] in ord
37660 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72  er to avoid.** r
37670 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20  esource leaks.  
37680 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73  It is a grievous
37690 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61   error for the a
376a0 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72  pplication to tr
376b0 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72  y to use.** a pr
376c0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
376d0 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
376e0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41  en finalized.  A
376f0 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70  ny use of a prep
37700 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
37710 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
37720 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61  een finalized ca
37730 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  n result in unde
37740 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64  fined and.** und
37750 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f  esirable behavio
37760 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75  r such as segfau
37770 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72  lts and heap cor
37780 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49  ruption..*/.SQLI
37790 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
377a0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69  e3_finalize(sqli
377b0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
377c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
377d0 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61  F: Reset A Prepa
377e0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
377f0 6a 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ject.** METHOD: 
37800 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
37810 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72  ** The sqlite3_r
37820 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  eset() function 
37830 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73  is called to res
37840 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  et a [prepared s
37850 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a  tatement].** obj
37860 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ect back to its 
37870 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72  initial state, r
37880 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78  eady to be re-ex
37890 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20  ecuted..** ^Any 
378a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61  SQL statement va
378b0 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64  riables that had
378c0 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f   values bound to
378d0 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74   them using.** t
378e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
378f0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
37900 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65  bind_*() API] re
37910 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65  tain their value
37920 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74  s..** Use [sqlit
37930 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
37940 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  s()] to reset th
37950 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a  e bindings..**.*
37960 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
37970 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
37980 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b  ace resets the [
37990 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
379a0 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f  nt] S.** back to
379b0 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
379c0 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a  f its program..*
379d0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
379e0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
379f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
37a00 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
37a10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
37a20 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53  t] S returned [S
37a30 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53  QLITE_ROW] or [S
37a40 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20  QLITE_DONE],.** 
37a50 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73  or if [sqlite3_s
37a60 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65  tep(S)] has neve
37a70 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61  r before been ca
37a80 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68  lled on S,.** th
37a90 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  en [sqlite3_rese
37aa0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53  t(S)] returns [S
37ab0 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
37ac0 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
37ad0 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cent call to [sq
37ae0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66  lite3_step(S)] f
37af0 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  or the.** [prepa
37b00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
37b10 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72   indicated an er
37b20 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71  ror, then.** [sq
37b30 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
37b40 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f  returns an appro
37b50 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
37b60 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
37b70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
37b80 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65  )] interface doe
37b90 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
37ba0 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e   values.** of an
37bb0 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  y [sqlite3_bind_
37bc0 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f  blob|bindings] o
37bd0 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
37be0 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f  statement] S..*/
37bf0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
37c00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
37c10 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
37c20 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
37c30 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
37c40 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
37c50 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
37c60 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
37c70 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
37c80 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
37c90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37ca0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
37cb0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
37cc0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
37cd0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
37ce0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
37cf0 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  te3.**.** ^These
37d00 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
37d10 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
37d20 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
37d30 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
37d40 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
37d50 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
37d60 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
37d70 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
37d80 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
37d90 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
37da0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
37db0 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
37dc0 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
37dd0 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
37de0 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
37df0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
37e00 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
37e10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
37e20 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
37e30 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
37e40 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
37e50 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
37e60 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
37e70 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
37e80 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
37e90 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
37ea0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
37eb0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
37ec0 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
37ed0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
37ee0 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
37ef0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
37f00 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
37f10 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
37f20 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
37f30 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
37f40 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
37f50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37f60 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
37f70 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
37f80 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
37f90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
37fa0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
37fb0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
37fc0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
37fd0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
37fe0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
37ff0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
38000 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
38010 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
38020 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
38030 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
38040 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
38050 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
38060 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
38070 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
38080 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
38090 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
380a0 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
380b0 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
380c0 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
380d0 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
380e0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
380f0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
38100 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
38110 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
38120 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
38130 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
38140 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
38150 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
38160 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
38170 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
38180 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
38190 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
381a0 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
381b0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
381c0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
381d0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
381e0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
381f0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
38200 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
38210 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
38220 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
38230 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
38240 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
38250 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
38260 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
38270 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
38280 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
38290 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
382a0 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
382b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
382c0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
382d0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
382e0 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
382f0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
38300 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
38310 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
38320 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
38330 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
38340 72 73 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  rs.  The applica
38350 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73 65 74 20  tion should set 
38360 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74  this parameter t
38370 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  o.** [SQLITE_UTF
38380 31 36 4c 45 5d 20 69 66 20 74 68 65 20 66 75 6e  16LE] if the fun
38390 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
383a0 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a  tion invokes .**
383b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
383c0 74 65 78 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61  text16le()] on a
383d0 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c  n input, or [SQL
383e0 49 54 45 5f 55 54 46 31 36 42 45 5d 20 69 66 20  ITE_UTF16BE] if 
383f0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
38400 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73  ation invokes [s
38410 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
38420 74 31 36 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16be()] on an i
38430 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c  nput, or.** [SQL
38440 49 54 45 5f 55 54 46 31 36 5d 20 69 66 20 5b 73  ITE_UTF16] if [s
38450 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
38460 74 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  t16()] is used, 
38470 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  or [SQLITE_UTF8]
38480 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 2e 20 20  .** otherwise.  
38490 5e 54 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75  ^The same SQL fu
384a0 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
384b0 67 69 73 74 65 72 65 64 20 6d 75 6c 74 69 70 6c  gistered multipl
384c0 65 20 74 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a  e times using.**
384d0 20 64 69 66 66 65 72 65 6e 74 20 70 72 65 66 65   different prefe
384e0 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
384f0 6e 67 73 2c 20 77 69 74 68 20 64 69 66 66 65 72  ngs, with differ
38500 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
38510 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ons for.** each 
38520 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68  encoding..** ^Wh
38530 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
38540 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
38550 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
38560 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
38570 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
38580 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
38590 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
385a0 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
385b0 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
385c0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
385d0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 6f   parameter may o
385e0 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65  ptionally be ORe
385f0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
38600 45 54 45 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a  ETERMINISTIC].**
38610 20 74 6f 20 73 69 67 6e 61 6c 20 74 68 61 74 20   to signal that 
38620 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  the function wil
38630 6c 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  l always return 
38640 74 68 65 20 73 61 6d 65 20 72 65 73 75 6c 74 20  the same result 
38650 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  given.** the sam
38660 65 20 69 6e 70 75 74 73 20 77 69 74 68 69 6e 20  e inputs within 
38670 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
38680 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51  tement.  Most SQ
38690 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a  L functions are.
386a0 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ** deterministic
386b0 2e 20 20 54 68 65 20 62 75 69 6c 74 2d 69 6e 20  .  The built-in 
386c0 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66  [random()] SQL f
386d0 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e 20 65 78  unction is an ex
386e0 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75  ample of a.** fu
386f0 6e 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6e  nction that is n
38700 6f 74 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  ot deterministic
38710 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 71 75  .  The SQLite qu
38720 65 72 79 20 70 6c 61 6e 6e 65 72 20 69 73 20 61  ery planner is a
38730 62 6c