System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 85e4e1c08c7df28ef61bb9759a0d466e0eefbaa2:


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 38 2e 31 30 2e 31 2e  ersion 3.8.10.1.
00b0: 20 20 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61    By combining a
00c0: 6c 6c 20 74 68 65 20 69 6e 64 69 76 69 64 75 61  ll the individua
00d0: 6c 20 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69  l C code files i
00e0: 6e 74 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e  nto this .** sin
00f0: 67 6c 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20  gle large file, 
0100: 74 68 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20  the entire code 
0110: 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  can be compiled 
0120: 61 73 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e  as a single tran
0130: 73 6c 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e  slation.** unit.
0140: 20 20 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61    This allows ma
0150: 6e 79 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20  ny compilers to 
0160: 64 6f 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73  do optimizations
0170: 20 74 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20   that would not 
0180: 62 65 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69  be.** possible i
0190: 66 20 74 68 65 20 66 69 6c 65 73 20 77 65 72 65  f the files were
01a0: 20 63 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61   compiled separa
01b0: 74 65 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e  tely.  Performan
01c0: 63 65 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a  ce improvements.
01d0: 2a 2a 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65  ** of 5% or more
01e0: 20 61 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65   are commonly se
01f0: 65 6e 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  en when SQLite i
0200: 73 20 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20  s compiled as a 
0210: 73 69 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c  single.** transl
0220: 61 74 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a  ation unit..**.*
0230: 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20 61  * This file is a
0240: 6c 6c 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63  ll you need to c
0250: 6f 6d 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20  ompile SQLite.  
0260: 54 6f 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e  To use SQLite in
0270: 20 6f 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61   other.** progra
0280: 6d 73 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69  ms, you need thi
0290: 73 20 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22  s file and the "
02a0: 73 71 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65  sqlite3.h" heade
02b0: 72 20 66 69 6c 65 20 74 68 61 74 20 64 65 66 69  r file that defi
02c0: 6e 65 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72  nes.** the progr
02d0: 61 6d 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65  amming interface
02e0: 20 74 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   to the SQLite l
02f0: 69 62 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75  ibrary.  (If you
0300: 20 64 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a   do not have .**
0310: 20 74 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22   the "sqlite3.h"
0320: 20 68 65 61 64 65 72 20 66 69 6c 65 20 61 74 20   header file at 
0330: 68 61 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66  hand, you will f
0340: 69 6e 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64  ind a copy embed
0350: 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  ded within.** th
0360: 65 20 74 65 78 74 20 6f 66 20 74 68 69 73 20 66  e text of this f
0370: 69 6c 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72  ile.  Search for
0380: 20 22 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c   "Begin file sql
0390: 69 74 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20  ite3.h" to find 
03a0: 74 68 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20  the start.** of 
03b0: 74 68 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c  the embedded sql
03c0: 69 74 65 33 2e 68 20 68 65 61 64 65 72 20 66 69  ite3.h header fi
03d0: 6c 65 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20  le.) Additional 
03e0: 63 6f 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62  code files may b
03f0: 65 20 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79  e needed.** if y
0400: 6f 75 20 77 61 6e 74 20 61 20 77 72 61 70 70 65  ou want a wrappe
0410: 72 20 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53  r to interface S
0420: 51 4c 69 74 65 20 77 69 74 68 20 79 6f 75 72 20  QLite with your 
0430: 63 68 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61  choice of progra
0440: 6d 6d 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67  mming.** languag
0450: 65 2e 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20  e. The code for 
0460: 74 68 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f  the "sqlite3" co
0470: 6d 6d 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c  mmand-line shell
0480: 20 69 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a   is also in a.**
0490: 20 73 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20   separate file. 
04a0: 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69  This file contai
04b0: 6e 73 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72  ns only code for
04c0: 20 74 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65   the core SQLite
04d0: 20 6c 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65   library..*/.#de
04e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45  fine SQLITE_CORE
04f0: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
0500: 45 5f 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31  E_AMALGAMATION 1
0510: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
0520: 50 52 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65  PRIVATE.# define
0530: 20 53 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20   SQLITE_PRIVATE 
0540: 73 74 61 74 69 63 0a 23 65 6e 64 69 66 0a 2f 2a  static.#endif./*
0550: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65  ************* Be
0560: 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65 49  gin file sqliteI
0570: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  nt.h ***********
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 2a 2a 2a 2a 2f 0a 2f 2a  ************/./*
05a0: 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 6d 62  .** 2001 Septemb
05b0: 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er 15.**.** The 
05c0: 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73  author disclaims
05d0: 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68   copyright to th
05e0: 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20  is source code. 
05f0: 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   In place of.** 
0600: 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20  a legal notice, 
0610: 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 73 69  here is a blessi
0620: 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79  ng:.**.**    May
0630: 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64   you do good and
0640: 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20   not evil..**   
0650: 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f   May you find fo
0660: 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f  rgiveness for yo
0670: 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69  urself and forgi
0680: 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20  ve others..**   
0690: 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20 66   May you share f
06a0: 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b  reely, never tak
06b0: 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f  ing more than yo
06c0: 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a  u give..**.*****
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: 2a 2a 2a 2a 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c  ****.** Internal
0720: 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e   interface defin
0730: 69 74 69 6f 6e 73 20 66 6f 72 20 53 51 4c 69 74  itions for SQLit
0740: 65 2e 0a 2a 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66  e..**.*/.#ifndef
0750: 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f 0a 23   _SQLITEINT_H_.#
0760: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 49 4e  define _SQLITEIN
0770: 54 5f 48 5f 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c  T_H_../*.** Incl
0780: 75 64 65 20 74 68 65 20 68 65 61 64 65 72 20 66  ude the header f
0790: 69 6c 65 20 75 73 65 64 20 74 6f 20 63 75 73 74  ile used to cust
07a0: 6f 6d 69 7a 65 20 74 68 65 20 63 6f 6d 70 69 6c  omize the compil
07b0: 65 72 20 6f 70 74 69 6f 6e 73 20 66 6f 72 20 4d  er options for M
07c0: 53 56 43 2e 0a 2a 2a 20 54 68 69 73 20 73 68 6f  SVC..** This sho
07d0: 75 6c 64 20 62 65 20 64 6f 6e 65 20 66 69 72 73  uld be done firs
07e0: 74 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  t so that it can
07f0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 70 72   successfully pr
0800: 65 76 65 6e 74 20 73 70 75 72 69 6f 75 73 0a 2a  event spurious.*
0810: 2a 20 63 6f 6d 70 69 6c 65 72 20 77 61 72 6e 69  * compiler warni
0820: 6e 67 73 20 64 75 65 20 74 6f 20 73 75 62 73 65  ngs due to subse
0830: 71 75 65 6e 74 20 63 6f 6e 74 65 6e 74 20 69 6e  quent content in
0840: 20 74 68 69 73 20 66 69 6c 65 20 61 6e 64 20 6f   this file and o
0850: 74 68 65 72 20 66 69 6c 65 73 0a 2a 2a 20 74 68  ther files.** th
0860: 61 74 20 61 72 65 20 69 6e 63 6c 75 64 65 64 20  at are included 
0870: 62 79 20 74 68 69 73 20 66 69 6c 65 2e 0a 2a 2f  by this file..*/
0880: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
0890: 20 49 6e 63 6c 75 64 65 20 6d 73 76 63 2e 68 20   Include msvc.h 
08a0: 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
08b0: 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a   sqliteInt.h ***
08c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
08d0: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
08e0: 20 42 65 67 69 6e 20 66 69 6c 65 20 6d 73 76 63   Begin file msvc
08f0: 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .h *************
0900: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0910: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
0920: 0a 2f 2a 0a 2a 2a 20 32 30 31 35 20 4a 61 6e 75  ./*.** 2015 Janu
0930: 61 72 79 20 31 32 0a 2a 2a 0a 2a 2a 20 54 68 65  ary 12.**.** The
0940: 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d   author disclaim
0950: 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74  s copyright to t
0960: 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e  his source code.
0970: 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a    In place of.**
0980: 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c   a legal notice,
0990: 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 73   here is a bless
09a0: 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61  ing:.**.**    Ma
09b0: 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e  y you do good an
09c0: 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20  d not evil..**  
09d0: 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66    May you find f
09e0: 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79  orgiveness for y
09f0: 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67  ourself and forg
0a00: 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20  ive others..**  
0a10: 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20    May you share 
0a20: 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61  freely, never ta
0a30: 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79  king more than y
0a40: 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a  ou give..**.****
0a50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0a90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 0a 2a 2a  **********.**.**
0aa0: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 61   This file conta
0ab0: 69 6e 73 20 63 6f 64 65 20 74 68 61 74 20 69 73  ins code that is
0ac0: 20 73 70 65 63 69 66 69 63 20 74 6f 20 4d 53 56   specific to MSV
0ad0: 43 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 4d  C..*/.#ifndef _M
0ae0: 53 56 43 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  SVC_H_.#define _
0af0: 4d 53 56 43 5f 48 5f 0a 0a 23 69 66 20 64 65 66  MSVC_H_..#if def
0b00: 69 6e 65 64 28 5f 4d 53 43 5f 56 45 52 29 0a 23  ined(_MSC_VER).#
0b10: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64  pragma warning(d
0b20: 69 73 61 62 6c 65 20 3a 20 34 30 35 34 29 0a 23  isable : 4054).#
0b30: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64  pragma warning(d
0b40: 69 73 61 62 6c 65 20 3a 20 34 30 35 35 29 0a 23  isable : 4055).#
0b50: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64  pragma warning(d
0b60: 69 73 61 62 6c 65 20 3a 20 34 31 30 30 29 0a 23  isable : 4100).#
0b70: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64  pragma warning(d
0b80: 69 73 61 62 6c 65 20 3a 20 34 31 32 37 29 0a 23  isable : 4127).#
0b90: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64  pragma warning(d
0ba0: 69 73 61 62 6c 65 20 3a 20 34 31 33 30 29 0a 23  isable : 4130).#
0bb0: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64  pragma warning(d
0bc0: 69 73 61 62 6c 65 20 3a 20 34 31 35 32 29 0a 23  isable : 4152).#
0bd0: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64  pragma warning(d
0be0: 69 73 61 62 6c 65 20 3a 20 34 31 38 39 29 0a 23  isable : 4189).#
0bf0: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64  pragma warning(d
0c00: 69 73 61 62 6c 65 20 3a 20 34 32 30 36 29 0a 23  isable : 4206).#
0c10: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64  pragma warning(d
0c20: 69 73 61 62 6c 65 20 3a 20 34 32 31 30 29 0a 23  isable : 4210).#
0c30: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64  pragma warning(d
0c40: 69 73 61 62 6c 65 20 3a 20 34 32 33 32 29 0a 23  isable : 4232).#
0c50: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64  pragma warning(d
0c60: 69 73 61 62 6c 65 20 3a 20 34 32 34 34 29 0a 23  isable : 4244).#
0c70: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64  pragma warning(d
0c80: 69 73 61 62 6c 65 20 3a 20 34 33 30 35 29 0a 23  isable : 4305).#
0c90: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64  pragma warning(d
0ca0: 69 73 61 62 6c 65 20 3a 20 34 33 30 36 29 0a 23  isable : 4306).#
0cb0: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64  pragma warning(d
0cc0: 69 73 61 62 6c 65 20 3a 20 34 37 30 32 29 0a 23  isable : 4702).#
0cd0: 70 72 61 67 6d 61 20 77 61 72 6e 69 6e 67 28 64  pragma warning(d
0ce0: 69 73 61 62 6c 65 20 3a 20 34 37 30 36 29 0a 23  isable : 4706).#
0cf0: 65 6e 64 69 66 20 2f 2a 20 64 65 66 69 6e 65 64  endif /* defined
0d00: 28 5f 4d 53 43 5f 56 45 52 29 20 2a 2f 0a 0a 23  (_MSC_VER) */..#
0d10: 65 6e 64 69 66 20 2f 2a 20 5f 4d 53 56 43 5f 48  endif /* _MSVC_H
0d20: 5f 20 2a 2f 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  _ */../*********
0d30: 2a 2a 2a 2a 2a 20 45 6e 64 20 6f 66 20 6d 73 76  ***** End of msv
0d40: 63 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  c.h ************
0d50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d70: 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****/./*********
0d80: 2a 2a 2a 2a 2a 20 43 6f 6e 74 69 6e 75 69 6e 67  ***** Continuing
0d90: 20 77 68 65 72 65 20 77 65 20 6c 65 66 74 20 6f   where we left o
0da0: 66 66 20 69 6e 20 73 71 6c 69 74 65 49 6e 74 2e  ff in sqliteInt.
0db0: 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  h **************
0dc0: 2a 2a 2a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  ****/../*.** Spe
0dd0: 63 69 61 6c 20 73 65 74 75 70 20 66 6f 72 20 56  cial setup for V
0de0: 78 57 6f 72 6b 73 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a  xWorks.*/./*****
0df0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64  ********* Includ
0e00: 65 20 76 78 77 6f 72 6b 73 2e 68 20 69 6e 20 74  e vxworks.h in t
0e10: 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c  he middle of sql
0e20: 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a  iteInt.h *******
0e30: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a  ********/./*****
0e40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20  ********* Begin 
0e50: 66 69 6c 65 20 76 78 77 6f 72 6b 73 2e 68 20 2a  file vxworks.h *
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20  ********/./*.** 
0e90: 32 30 31 35 2d 30 33 2d 30 32 0a 2a 2a 0a 2a 2a  2015-03-02.**.**
0ea0: 20 54 68 65 20 61 75 74 68 6f 72 20 64 69 73 63   The author disc
0eb0: 6c 61 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20  laims copyright 
0ec0: 74 6f 20 74 68 69 73 20 73 6f 75 72 63 65 20 63  to this source c
0ed0: 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f  ode.  In place o
0ee0: 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74  f.** a legal not
0ef0: 69 63 65 2c 20 68 65 72 65 20 69 73 20 61 20 62  ice, here is a b
0f00: 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20  lessing:.**.**  
0f10: 20 20 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f    May you do goo
0f20: 64 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a  d and not evil..
0f30: 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69  **    May you fi
0f40: 6e 64 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66  nd forgiveness f
0f50: 6f 72 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20  or yourself and 
0f60: 66 6f 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a  forgive others..
0f70: 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68  **    May you sh
0f80: 61 72 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65  are freely, neve
0f90: 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68  r taking more th
0fa0: 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a  an you give..**.
0fb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0fe0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ff0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a  **************.*
1000: 2a 0a 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63  *.** This file c
1010: 6f 6e 74 61 69 6e 73 20 63 6f 64 65 20 74 68 61  ontains code tha
1020: 74 20 69 73 20 73 70 65 63 69 66 69 63 20 74 6f  t is specific to
1030: 20 57 69 6e 64 20 52 69 76 65 72 27 73 20 56 78   Wind River's Vx
1040: 57 6f 72 6b 73 0a 2a 2f 0a 23 69 66 20 64 65 66  Works.*/.#if def
1050: 69 6e 65 64 28 5f 5f 52 54 50 5f 5f 29 20 7c 7c  ined(__RTP__) ||
1060: 20 64 65 66 69 6e 65 64 28 5f 57 52 53 5f 4b 45   defined(_WRS_KE
1070: 52 4e 45 4c 29 0a 2f 2a 20 54 68 69 73 20 69 73  RNEL)./* This is
1080: 20 56 78 57 6f 72 6b 73 2e 20 20 53 65 74 20 75   VxWorks.  Set u
1090: 70 20 74 68 69 6e 67 73 20 73 70 65 63 69 61 6c  p things special
10a0: 6c 79 20 66 6f 72 20 74 68 61 74 20 4f 53 0a 2a  ly for that OS.*
10b0: 2f 0a 23 69 6e 63 6c 75 64 65 20 3c 76 78 57 6f  /.#include <vxWo
10c0: 72 6b 73 2e 68 3e 0a 23 69 6e 63 6c 75 64 65 20  rks.h>.#include 
10d0: 3c 70 74 68 72 65 61 64 2e 68 3e 20 20 2f 2a 20  <pthread.h>  /* 
10e0: 61 6d 61 6c 67 61 6d 61 74 6f 72 3a 20 64 6f 6e  amalgamator: don
10f0: 74 63 61 63 68 65 20 2a 2f 0a 23 64 65 66 69 6e  tcache */.#defin
1100: 65 20 4f 53 5f 56 58 57 4f 52 4b 53 20 31 0a 23  e OS_VXWORKS 1.#
1110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 53  define SQLITE_OS
1120: 5f 4f 54 48 45 52 20 30 0a 23 64 65 66 69 6e 65  _OTHER 0.#define
1130: 20 53 51 4c 49 54 45 5f 48 4f 4d 45 47 52 4f 57   SQLITE_HOMEGROW
1140: 4e 5f 52 45 43 55 52 53 49 56 45 5f 4d 55 54 45  N_RECURSIVE_MUTE
1150: 58 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  X 1.#define SQLI
1160: 54 45 5f 4f 4d 49 54 5f 4c 4f 41 44 5f 45 58 54  TE_OMIT_LOAD_EXT
1170: 45 4e 53 49 4f 4e 20 31 0a 23 64 65 66 69 6e 65  ENSION 1.#define
1180: 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4c   SQLITE_ENABLE_L
1190: 4f 43 4b 49 4e 47 5f 53 54 59 4c 45 20 30 0a 23  OCKING_STYLE 0.#
11a0: 64 65 66 69 6e 65 20 48 41 56 45 5f 55 54 49 4d  define HAVE_UTIM
11b0: 45 20 31 0a 23 65 6c 73 65 0a 2f 2a 20 54 68 69  E 1.#else./* Thi
11c0: 73 20 69 73 20 6e 6f 74 20 56 78 57 6f 72 6b 73  s is not VxWorks
11d0: 2e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 4f 53 5f  . */.#define OS_
11e0: 56 58 57 4f 52 4b 53 20 30 0a 23 65 6e 64 69 66  VXWORKS 0.#endif
11f0: 20 2f 2a 20 64 65 66 69 6e 65 64 28 5f 57 52 53   /* defined(_WRS
1200: 5f 4b 45 52 4e 45 4c 29 20 2a 2f 0a 0a 2f 2a 2a  _KERNEL) */../**
1210: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 45 6e 64  ************ End
1220: 20 6f 66 20 76 78 77 6f 72 6b 73 2e 68 20 2a 2a   of vxworks.h **
1230: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1240: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1250: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a  ***********/./**
1260: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 43 6f 6e  ************ Con
1270: 74 69 6e 75 69 6e 67 20 77 68 65 72 65 20 77 65  tinuing where we
1280: 20 6c 65 66 74 20 6f 66 66 20 69 6e 20 73 71 6c   left off in sql
1290: 69 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a  iteInt.h *******
12a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 0a 2f 2a  ***********/../*
12b0: 0a 2a 2a 20 54 68 65 73 65 20 23 64 65 66 69 6e  .** These #defin
12c0: 65 73 20 73 68 6f 75 6c 64 20 65 6e 61 62 6c 65  es should enable
12d0: 20 3e 32 47 42 20 66 69 6c 65 20 73 75 70 70 6f   >2GB file suppo
12e0: 72 74 20 6f 6e 20 50 4f 53 49 58 20 69 66 20 74  rt on POSIX if t
12f0: 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67  he.** underlying
1300: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1310: 6d 20 73 75 70 70 6f 72 74 73 20 69 74 2e 20 20  m supports it.  
1320: 49 66 20 74 68 65 20 4f 53 20 6c 61 63 6b 73 0a  If the OS lacks.
1330: 2a 2a 20 6c 61 72 67 65 20 66 69 6c 65 20 73 75  ** large file su
1340: 70 70 6f 72 74 2c 20 6f 72 20 69 66 20 74 68 65  pport, or if the
1350: 20 4f 53 20 69 73 20 77 69 6e 64 6f 77 73 2c 20   OS is windows, 
1360: 74 68 65 73 65 20 73 68 6f 75 6c 64 20 62 65 20  these should be 
1370: 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a 2a 20 54 69  no-ops..**.** Ti
1380: 63 6b 65 74 20 23 32 37 33 39 3a 20 20 54 68 65  cket #2739:  The
1390: 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 52   _LARGEFILE_SOUR
13a0: 43 45 20 6d 61 63 72 6f 20 6d 75 73 74 20 61 70  CE macro must ap
13b0: 70 65 61 72 20 62 65 66 6f 72 65 20 61 6e 79 0a  pear before any.
13c0: 2a 2a 20 73 79 73 74 65 6d 20 23 69 6e 63 6c 75  ** system #inclu
13d0: 64 65 73 2e 20 20 48 65 6e 63 65 2c 20 74 68 69  des.  Hence, thi
13e0: 73 20 62 6c 6f 63 6b 20 6f 66 20 63 6f 64 65 20  s block of code 
13f0: 6d 75 73 74 20 62 65 20 74 68 65 20 76 65 72 79  must be the very
1400: 20 66 69 72 73 74 0a 2a 2a 20 63 6f 64 65 20 69   first.** code i
1410: 6e 20 61 6c 6c 20 73 6f 75 72 63 65 20 66 69 6c  n all source fil
1420: 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61 72 67 65 20  es..**.** Large 
1430: 66 69 6c 65 20 73 75 70 70 6f 72 74 20 63 61 6e  file support can
1440: 20 62 65 20 64 69 73 61 62 6c 65 64 20 75 73 69   be disabled usi
1450: 6e 67 20 74 68 65 20 2d 44 53 51 4c 49 54 45 5f  ng the -DSQLITE_
1460: 44 49 53 41 42 4c 45 5f 4c 46 53 20 73 77 69 74  DISABLE_LFS swit
1470: 63 68 0a 2a 2a 20 6f 6e 20 74 68 65 20 63 6f 6d  ch.** on the com
1480: 70 69 6c 65 72 20 63 6f 6d 6d 61 6e 64 20 6c 69  piler command li
1490: 6e 65 2e 20 20 54 68 69 73 20 69 73 20 6e 65 63  ne.  This is nec
14a0: 65 73 73 61 72 79 20 69 66 20 79 6f 75 20 61 72  essary if you ar
14b0: 65 20 63 6f 6d 70 69 6c 69 6e 67 0a 2a 2a 20 6f  e compiling.** o
14c0: 6e 20 61 20 72 65 63 65 6e 74 20 6d 61 63 68 69  n a recent machi
14d0: 6e 65 20 28 65 78 3a 20 52 65 64 20 48 61 74 20  ne (ex: Red Hat 
14e0: 37 2e 32 29 20 62 75 74 20 79 6f 75 20 77 61 6e  7.2) but you wan
14f0: 74 20 79 6f 75 72 20 63 6f 64 65 20 74 6f 20 77  t your code to w
1500: 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e 20 6f 6c 64  ork.** on an old
1510: 65 72 20 6d 61 63 68 69 6e 65 20 28 65 78 3a 20  er machine (ex: 
1520: 52 65 64 20 48 61 74 20 36 2e 30 29 2e 20 20 49  Red Hat 6.0).  I
1530: 66 20 79 6f 75 20 63 6f 6d 70 69 6c 65 20 6f 6e  f you compile on
1540: 20 52 65 64 20 48 61 74 20 37 2e 32 0a 2a 2a 20   Red Hat 7.2.** 
1550: 77 69 74 68 6f 75 74 20 74 68 69 73 20 6f 70 74  without this opt
1560: 69 6f 6e 2c 20 4c 46 53 20 69 73 20 65 6e 61 62  ion, LFS is enab
1570: 6c 65 2e 20 20 42 75 74 20 4c 46 53 20 64 6f 65  le.  But LFS doe
1580: 73 20 6e 6f 74 20 65 78 69 73 74 20 69 6e 20 74  s not exist in t
1590: 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a 20 69 6e 20  he kernel.** in 
15a0: 52 65 64 20 48 61 74 20 36 2e 30 2c 20 73 6f 20  Red Hat 6.0, so 
15b0: 74 68 65 20 63 6f 64 65 20 77 6f 6e 27 74 20 77  the code won't w
15c0: 6f 72 6b 2e 20 20 48 65 6e 63 65 2c 20 66 6f 72  ork.  Hence, for
15d0: 20 6d 61 78 69 6d 75 6d 20 62 69 6e 61 72 79 0a   maximum binary.
15e0: 2a 2a 20 70 6f 72 74 61 62 69 6c 69 74 79 20 79  ** portability y
15f0: 6f 75 20 73 68 6f 75 6c 64 20 6f 6d 69 74 20 4c  ou should omit L
1600: 46 53 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  FS..**.** The pr
1610: 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
1620: 20 77 61 73 20 77 72 69 74 74 65 6e 20 69 6e 20   was written in 
1630: 32 30 30 35 2e 20 20 28 54 68 69 73 20 70 61 72  2005.  (This par
1640: 61 67 72 61 70 68 20 69 73 20 77 72 69 74 74 65  agraph is writte
1650: 6e 0a 2a 2a 20 6f 6e 20 32 30 30 38 2d 31 31 2d  n.** on 2008-11-
1660: 32 38 2e 29 20 54 68 65 73 65 20 64 61 79 73 2c  28.) These days,
1670: 20 61 6c 6c 20 4c 69 6e 75 78 20 6b 65 72 6e 65   all Linux kerne
1680: 6c 73 20 73 75 70 70 6f 72 74 20 6c 61 72 67 65  ls support large
1690: 20 66 69 6c 65 73 2c 20 73 6f 0a 2a 2a 20 79 6f   files, so.** yo
16a0: 75 20 73 68 6f 75 6c 64 20 70 72 6f 62 61 62 6c  u should probabl
16b0: 79 20 6c 65 61 76 65 20 4c 46 53 20 65 6e 61 62  y leave LFS enab
16c0: 6c 65 64 2e 20 20 42 75 74 20 73 6f 6d 65 20 65  led.  But some e
16d0: 6d 62 65 64 64 65 64 20 70 6c 61 74 66 6f 72 6d  mbedded platform
16e0: 73 20 6d 69 67 68 74 0a 2a 2a 20 6c 61 63 6b 20  s might.** lack 
16f0: 4c 46 53 20 69 6e 20 77 68 69 63 68 20 63 61 73  LFS in which cas
1700: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 44 49 53  e the SQLITE_DIS
1710: 41 42 4c 45 5f 4c 46 53 20 6d 61 63 72 6f 20 6d  ABLE_LFS macro m
1720: 69 67 68 74 20 73 74 69 6c 6c 20 62 65 20 75 73  ight still be us
1730: 65 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 53 69 6d 69  eful..**.** Simi
1740: 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f 72 20  lar is true for 
1750: 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53 20 69  Mac OS X.  LFS i
1760: 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74 65 64  s only supported
1770: 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39 20 61   on Mac OS X 9 a
1780: 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23 69 66  nd later..*/.#if
1790: 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49 53 41  ndef SQLITE_DISA
17a0: 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69 6e 65  BLE_LFS.# define
17b0: 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20 20 20   _LARGE_FILE    
17c0: 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20 5f 46     1.# ifndef _F
17d0: 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 0a  ILE_OFFSET_BITS.
17e0: 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49 4c 45  #   define _FILE
17f0: 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36 34 0a  _OFFSET_BITS 64.
1800: 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69 6e 65  # endif.# define
1810: 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f 55 52   _LARGEFILE_SOUR
1820: 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20  CE 1.#endif../* 
1830: 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f  Needed for vario
1840: 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e  us definitions..
1850: 2e 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64  . */.#if defined
1860: 28 5f 5f 47 4e 55 43 5f 5f 29 20 26 26 20 21 64  (__GNUC__) && !d
1870: 65 66 69 6e 65 64 28 5f 47 4e 55 5f 53 4f 55 52  efined(_GNU_SOUR
1880: 43 45 29 0a 23 20 64 65 66 69 6e 65 20 5f 47 4e  CE).# define _GN
1890: 55 5f 53 4f 55 52 43 45 0a 23 65 6e 64 69 66 0a  U_SOURCE.#endif.
18a0: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f 4f  .#if defined(__O
18b0: 70 65 6e 42 53 44 5f 5f 29 20 26 26 20 21 64 65  penBSD__) && !de
18c0: 66 69 6e 65 64 28 5f 42 53 44 5f 53 4f 55 52 43  fined(_BSD_SOURC
18d0: 45 29 0a 23 20 64 65 66 69 6e 65 20 5f 42 53 44  E).# define _BSD
18e0: 5f 53 4f 55 52 43 45 0a 23 65 6e 64 69 66 0a 0a  _SOURCE.#endif..
18f0: 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69 6e 47 57 2c  /*.** For MinGW,
1900: 20 63 68 65 63 6b 20 74 6f 20 73 65 65 20 69 66   check to see if
1910: 20 77 65 20 63 61 6e 20 69 6e 63 6c 75 64 65 20   we can include 
1920: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 20  the header file 
1930: 63 6f 6e 74 61 69 6e 69 6e 67 20 69 74 73 0a 2a  containing its.*
1940: 2a 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d  * version inform
1950: 61 74 69 6f 6e 2c 20 61 6d 6f 6e 67 20 6f 74 68  ation, among oth
1960: 65 72 20 74 68 69 6e 67 73 2e 20 20 4e 6f 72 6d  er things.  Norm
1970: 61 6c 6c 79 2c 20 74 68 69 73 20 69 6e 74 65 72  ally, this inter
1980: 6e 61 6c 20 4d 69 6e 47 57 0a 2a 2a 20 68 65 61  nal MinGW.** hea
1990: 64 65 72 20 66 69 6c 65 20 77 6f 75 6c 64 20 5b  der file would [
19a0: 6f 6e 6c 79 5d 20 62 65 20 69 6e 63 6c 75 64 65  only] be include
19b0: 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
19c0: 62 79 20 6f 74 68 65 72 20 4d 69 6e 47 57 20 68  by other MinGW h
19d0: 65 61 64 65 72 0a 2a 2a 20 66 69 6c 65 73 3b 20  eader.** files; 
19e0: 68 6f 77 65 76 65 72 2c 20 74 68 65 20 63 6f 6e  however, the con
19f0: 74 61 69 6e 65 64 20 76 65 72 73 69 6f 6e 20 69  tained version i
1a00: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 6e 6f  nformation is no
1a10: 77 20 72 65 71 75 69 72 65 64 20 62 79 20 74 68  w required by th
1a20: 69 73 0a 2a 2a 20 68 65 61 64 65 72 20 66 69 6c  is.** header fil
1a30: 65 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  e to work around
1a40: 20 62 69 6e 61 72 79 20 63 6f 6d 70 61 74 69 62   binary compatib
1a50: 69 6c 69 74 79 20 69 73 73 75 65 73 20 28 73 65  ility issues (se
1a60: 65 20 62 65 6c 6f 77 29 20 61 6e 64 0a 2a 2a 20  e below) and.** 
1a70: 74 68 69 73 20 69 73 20 74 68 65 20 6f 6e 6c 79  this is the only
1a80: 20 6b 6e 6f 77 6e 20 77 61 79 20 74 6f 20 72 65   known way to re
1a90: 6c 69 61 62 6c 79 20 6f 62 74 61 69 6e 20 69 74  liably obtain it
1aa0: 2e 20 20 54 68 69 73 20 65 6e 74 69 72 65 20 23  .  This entire #
1ab0: 69 66 20 62 6c 6f 63 6b 0a 2a 2a 20 77 6f 75 6c  if block.** woul
1ac0: 64 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 20  d be completely 
1ad0: 75 6e 6e 65 63 65 73 73 61 72 79 20 69 66 20 74  unnecessary if t
1ae0: 68 65 72 65 20 77 61 73 20 61 6e 79 20 6f 74 68  here was any oth
1af0: 65 72 20 77 61 79 20 6f 66 20 64 65 74 65 63 74  er way of detect
1b00: 69 6e 67 0a 2a 2a 20 4d 69 6e 47 57 20 76 69 61  ing.** MinGW via
1b10: 20 74 68 65 69 72 20 70 72 65 70 72 6f 63 65 73   their preproces
1b20: 73 6f 72 20 28 65 2e 67 2e 20 69 66 20 74 68 65  sor (e.g. if the
1b30: 79 20 63 75 73 74 6f 6d 69 7a 65 64 20 74 68 65  y customized the
1b40: 69 72 20 47 43 43 20 74 6f 20 64 65 66 69 6e 65  ir GCC to define
1b50: 0a 2a 2a 20 73 6f 6d 65 20 4d 69 6e 47 57 2d 73  .** some MinGW-s
1b60: 70 65 63 69 66 69 63 20 6d 61 63 72 6f 73 29 2e  pecific macros).
1b70: 20 20 57 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67    When compiling
1b80: 20 66 6f 72 20 4d 69 6e 47 57 2c 20 65 69 74 68   for MinGW, eith
1b90: 65 72 20 74 68 65 0a 2a 2a 20 5f 48 41 56 45 5f  er the.** _HAVE_
1ba0: 4d 49 4e 47 57 5f 48 20 6f 72 20 5f 48 41 56 45  MINGW_H or _HAVE
1bb0: 5f 5f 4d 49 4e 47 57 5f 48 20 28 6e 6f 74 65 20  __MINGW_H (note 
1bc0: 74 68 65 20 65 78 74 72 61 20 75 6e 64 65 72 73  the extra unders
1bd0: 63 6f 72 65 29 20 6d 61 63 72 6f 20 6d 75 73 74  core) macro must
1be0: 20 62 65 0a 2a 2a 20 64 65 66 69 6e 65 64 3b 20   be.** defined; 
1bf0: 6f 74 68 65 72 77 69 73 65 2c 20 64 65 74 65 63  otherwise, detec
1c00: 74 69 6f 6e 20 6f 66 20 63 6f 6e 64 69 74 69 6f  tion of conditio
1c10: 6e 73 20 73 70 65 63 69 66 69 63 20 74 6f 20 4d  ns specific to M
1c20: 69 6e 47 57 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  inGW will be.** 
1c30: 64 69 73 61 62 6c 65 64 2e 0a 2a 2f 0a 23 69 66  disabled..*/.#if
1c40: 20 64 65 66 69 6e 65 64 28 5f 48 41 56 45 5f 4d   defined(_HAVE_M
1c50: 49 4e 47 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64  INGW_H).# includ
1c60: 65 20 22 6d 69 6e 67 77 2e 68 22 0a 23 65 6c 69  e "mingw.h".#eli
1c70: 66 20 64 65 66 69 6e 65 64 28 5f 48 41 56 45 5f  f defined(_HAVE_
1c80: 5f 4d 49 4e 47 57 5f 48 29 0a 23 20 69 6e 63 6c  _MINGW_H).# incl
1c90: 75 64 65 20 22 5f 6d 69 6e 67 77 2e 68 22 0a 23  ude "_mingw.h".#
1ca0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72  endif../*.** For
1cb0: 20 4d 69 6e 47 57 20 76 65 72 73 69 6f 6e 20 34   MinGW version 4
1cc0: 2e 78 20 28 61 6e 64 20 68 69 67 68 65 72 29 2c  .x (and higher),
1cd0: 20 63 68 65 63 6b 20 74 6f 20 73 65 65 20 69 66   check to see if
1ce0: 20 74 68 65 20 5f 55 53 45 5f 33 32 42 49 54 5f   the _USE_32BIT_
1cf0: 54 49 4d 45 5f 54 0a 2a 2a 20 64 65 66 69 6e 65  TIME_T.** define
1d00: 20 69 73 20 72 65 71 75 69 72 65 64 20 74 6f 20   is required to 
1d10: 6d 61 69 6e 74 61 69 6e 20 62 69 6e 61 72 79 20  maintain binary 
1d20: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
1d30: 74 68 20 74 68 65 20 4d 53 56 43 20 72 75 6e 74  th the MSVC runt
1d40: 69 6d 65 0a 2a 2a 20 6c 69 62 72 61 72 79 20 69  ime.** library i
1d50: 6e 20 75 73 65 20 28 65 2e 67 2e 20 66 6f 72 20  n use (e.g. for 
1d60: 57 69 6e 64 6f 77 73 20 58 50 29 2e 0a 2a 2f 0a  Windows XP)..*/.
1d70: 23 69 66 20 21 64 65 66 69 6e 65 64 28 5f 55 53  #if !defined(_US
1d80: 45 5f 33 32 42 49 54 5f 54 49 4d 45 5f 54 29 20  E_32BIT_TIME_T) 
1d90: 26 26 20 21 64 65 66 69 6e 65 64 28 5f 55 53 45  && !defined(_USE
1da0: 5f 36 34 42 49 54 5f 54 49 4d 45 5f 54 29 20 26  _64BIT_TIME_T) &
1db0: 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28  & \.    defined(
1dc0: 5f 57 49 4e 33 32 29 20 26 26 20 21 64 65 66 69  _WIN32) && !defi
1dd0: 6e 65 64 28 5f 57 49 4e 36 34 29 20 26 26 20 5c  ned(_WIN64) && \
1de0: 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f 5f 4d  .    defined(__M
1df0: 49 4e 47 57 5f 4d 41 4a 4f 52 5f 56 45 52 53 49  INGW_MAJOR_VERSI
1e00: 4f 4e 29 20 26 26 20 5f 5f 4d 49 4e 47 57 5f 4d  ON) && __MINGW_M
1e10: 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 20 3e 3d 20  AJOR_VERSION >= 
1e20: 34 20 26 26 20 5c 0a 20 20 20 20 64 65 66 69 6e  4 && \.    defin
1e30: 65 64 28 5f 5f 4d 53 56 43 52 54 5f 5f 29 0a 23  ed(__MSVCRT__).#
1e40: 20 64 65 66 69 6e 65 20 5f 55 53 45 5f 33 32 42   define _USE_32B
1e50: 49 54 5f 54 49 4d 45 5f 54 0a 23 65 6e 64 69 66  IT_TIME_T.#endif
1e60: 0a 0a 2f 2a 20 54 68 65 20 70 75 62 6c 69 63 20  ../* The public 
1e70: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
1e80: 2e 20 20 54 68 65 20 5f 46 49 4c 45 5f 4f 46 46  .  The _FILE_OFF
1e90: 53 45 54 5f 42 49 54 53 20 6d 61 63 72 6f 20 6d  SET_BITS macro m
1ea0: 75 73 74 20 61 70 70 65 61 72 0a 2a 2a 20 66 69  ust appear.** fi
1eb0: 72 73 74 20 69 6e 20 51 4e 58 2e 20 20 41 6c 73  rst in QNX.  Als
1ec0: 6f 2c 20 74 68 65 20 5f 55 53 45 5f 33 32 42 49  o, the _USE_32BI
1ed0: 54 5f 54 49 4d 45 5f 54 20 6d 61 63 72 6f 20 6d  T_TIME_T macro m
1ee0: 75 73 74 20 61 70 70 65 61 72 20 66 69 72 73 74  ust appear first
1ef0: 20 66 6f 72 0a 2a 2a 20 4d 69 6e 47 57 2e 0a 2a   for.** MinGW..*
1f00: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1f10: 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74 65  * Include sqlite
1f20: 33 2e 68 20 69 6e 20 74 68 65 20 6d 69 64 64 6c  3.h in the middl
1f30: 65 20 6f 66 20 73 71 6c 69 74 65 49 6e 74 2e 68  e of sqliteInt.h
1f40: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
1f50: 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1f60: 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c  * Begin file sql
1f70: 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ite3.h *********
1f80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1f90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1fa0: 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70  /./*.** 2001 Sep
1fb0: 74 65 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20  tember 15.**.** 
1fc0: 54 68 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c  The author discl
1fd0: 61 69 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74  aims copyright t
1fe0: 6f 20 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f  o this source co
1ff0: 64 65 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66  de.  In place of
2000: 0a 2a 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69  .** a legal noti
2010: 63 65 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c  ce, here is a bl
2020: 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20  essing:.**.**   
2030: 20 4d 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64   May you do good
2040: 20 61 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a   and not evil..*
2050: 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e  *    May you fin
2060: 64 20 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f  d forgiveness fo
2070: 72 20 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66  r yourself and f
2080: 6f 72 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a  orgive others..*
2090: 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61  *    May you sha
20a0: 72 65 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72  re freely, never
20b0: 20 74 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61   taking more tha
20c0: 6e 20 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a  n you give..**.*
20d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20e0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20f0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2100: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2110: 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73  ********.** This
2120: 20 68 65 61 64 65 72 20 66 69 6c 65 20 64 65 66   header file def
2130: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
2140: 63 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 69  ce that the SQLi
2150: 74 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72  te library.** pr
2160: 65 73 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74  esents to client
2170: 20 70 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61   programs.  If a
2180: 20 43 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72   C-function, str
2190: 75 63 74 75 72 65 2c 20 64 61 74 61 74 79 70 65  ucture, datatype
21a0: 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74  ,.** or constant
21b0: 20 64 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73   definition does
21c0: 20 6e 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74   not appear in t
21d0: 68 69 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69  his file, then i
21e0: 74 20 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75  t is.** not a pu
21f0: 62 6c 69 73 68 65 64 20 41 50 49 20 6f 66 20 53  blished API of S
2200: 51 4c 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63  QLite, is subjec
2210: 74 20 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68  t to change with
2220: 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61  out.** notice, a
2230: 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
2240: 20 72 65 66 65 72 65 6e 63 65 64 20 62 79 20 70   referenced by p
2250: 72 6f 67 72 61 6d 73 20 74 68 61 74 20 75 73 65  rograms that use
2260: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
2270: 6f 6d 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e  ome of the defin
2280: 69 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  itions that are 
2290: 69 6e 20 74 68 69 73 20 66 69 6c 65 20 61 72 65  in this file are
22a0: 20 6d 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65   marked as.** "e
22b0: 78 70 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45  xperimental".  E
22c0: 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65  xperimental inte
22d0: 72 66 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61  rfaces are norma
22e0: 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75  lly new.** featu
22f0: 72 65 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64  res recently add
2300: 65 64 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57  ed to SQLite.  W
2310: 65 20 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70  e do not anticip
2320: 61 74 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74  ate changes.** t
2330: 6f 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69  o experimental i
2340: 6e 74 65 72 66 61 63 65 73 20 62 75 74 20 72 65  nterfaces but re
2350: 73 65 72 76 65 20 74 68 65 20 72 69 67 68 74 20  serve the right 
2360: 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68  to make minor ch
2370: 61 6e 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65  anges.** if expe
2380: 72 69 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20  rience from use 
2390: 22 69 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75  "in the wild" su
23a0: 67 67 65 73 74 20 73 75 63 68 20 63 68 61 6e 67  ggest such chang
23b0: 65 73 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a  es are prudent..
23c0: 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69  **.** The offici
23d0: 61 6c 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50  al C-language AP
23e0: 49 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  I documentation 
23f0: 66 6f 72 20 53 51 4c 69 74 65 20 69 73 20 64 65  for SQLite is de
2400: 72 69 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f  rived.** from co
2410: 6d 6d 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66  mments in this f
2420: 69 6c 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20  ile.  This file 
2430: 69 73 20 74 68 65 20 61 75 74 68 6f 72 69 74 61  is the authorita
2440: 74 69 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f  tive source.** o
2450: 6e 20 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74  n how SQLite int
2460: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 70 70  erfaces are supp
2470: 6f 73 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a  ose to operate..
2480: 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f  **.** The name o
2490: 66 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65  f this file unde
24a0: 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
24b0: 6d 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73  management is "s
24c0: 71 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20  qlite.h.in"..** 
24d0: 54 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b  The makefile mak
24e0: 65 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68  es some minor ch
24f0: 61 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69  anges to this fi
2500: 6c 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65  le (such as inse
2510: 72 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72  rting.** the ver
2520: 73 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64  sion number) and
2530: 20 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d   changes its nam
2540: 65 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22  e to "sqlite3.h"
2550: 20 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74   as.** part of t
2560: 68 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73  he build process
2570: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51  ..*/.#ifndef _SQ
2580: 4c 49 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65  LITE3_H_.#define
2590: 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e   _SQLITE3_H_.#in
25a0: 63 6c 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e  clude <stdarg.h>
25b0: 20 20 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66       /* Needed f
25c0: 6f 72 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f  or the definitio
25d0: 6e 20 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a  n of va_list */.
25e0: 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65  ./*.** Make sure
25f0: 20 77 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69   we can call thi
2600: 73 20 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b  s stuff from C++
2610: 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65 78 74 65 72  ..*/.#if 0.exter
2620: 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a 0a  n "C" {.#endif..
2630: 0a 2f 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20 74  ./*.** Provide t
2640: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76  he ability to ov
2650: 65 72 72 69 64 65 20 6c 69 6e 6b 61 67 65 20 66  erride linkage f
2660: 65 61 74 75 72 65 73 20 6f 66 20 74 68 65 20 69  eatures of the i
2670: 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69 66  nterface..*/.#if
2680: 6e 64 65 66 20 53 51 4c 49 54 45 5f 45 58 54 45  ndef SQLITE_EXTE
2690: 52 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  RN.# define SQLI
26a0: 54 45 5f 45 58 54 45 52 4e 20 65 78 74 65 72 6e  TE_EXTERN extern
26b0: 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20  .#endif.#ifndef 
26c0: 53 51 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66  SQLITE_API.# def
26d0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23  ine SQLITE_API.#
26e0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
26f0: 4c 49 54 45 5f 43 44 45 43 4c 0a 23 20 64 65 66  LITE_CDECL.# def
2700: 69 6e 65 20 53 51 4c 49 54 45 5f 43 44 45 43 4c  ine SQLITE_CDECL
2710: 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20  .#endif.#ifndef 
2720: 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23  SQLITE_STDCALL.#
2730: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53   define SQLITE_S
2740: 54 44 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f  TDCALL.#endif../
2750: 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70  *.** These no-op
2760: 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64   macros are used
2770: 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74   in front of int
2780: 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20  erfaces to mark 
2790: 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  those.** interfa
27a0: 63 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65  ces as either de
27b0: 70 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65  precated or expe
27c0: 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61  rimental.  New a
27d0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
27e0: 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65  hould not use de
27f0: 70 72 65 63 61 74 65 64 20 69 6e 74 65 72 66 61  precated interfa
2800: 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 20 73  ces - they are s
2810: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
2820: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
2830: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41  ibility only.  A
2840: 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65  pplication write
2850: 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61  rs should be awa
2860: 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72  re that.** exper
2870: 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63  imental interfac
2880: 65 73 20 61 72 65 20 73 75 62 6a 65 63 74 20 74  es are subject t
2890: 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e  o change in poin
28a0: 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  t releases..**.*
28b0: 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75  * These macros u
28c0: 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74  sed to resolve t
28d0: 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20  o various kinds 
28e0: 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  of compiler magi
28f0: 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20  c that.** would 
2900: 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67  generate warning
2910: 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e 20 74   messages when t
2920: 68 65 79 20 77 65 72 65 20 75 73 65 64 2e 20 20  hey were used.  
2930: 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70  But that.** comp
2940: 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64  iler magic ended
2950: 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73   up generating s
2960: 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20  uch a flurry of 
2970: 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74  bug reports.** t
2980: 68 61 74 20 77 65 20 68 61 76 65 20 74 61 6b 65  hat we have take
2990: 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64  n it all out and
29a0: 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73   gone back to us
29b0: 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f  ing simple.** no
29c0: 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64  op macros..*/.#d
29d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50  efine SQLITE_DEP
29e0: 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20  RECATED.#define 
29f0: 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
2a00: 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72  TAL../*.** Ensur
2a10: 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20  e these symbols 
2a20: 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64  were not defined
2a30: 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75   by some previou
2a40: 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a  s header file..*
2a50: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
2a60: 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20  VERSION.# undef 
2a70: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
2a80: 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c  endif.#ifdef SQL
2a90: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
2aa0: 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  ER.# undef SQLIT
2ab0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
2ac0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
2ad0: 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
2ae0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
2af0: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a  rsion Numbers.**
2b00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
2b10: 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70 72 65  E_VERSION] C pre
2b20: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
2b30: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68  in the sqlite3.h
2b40: 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75   header.** evalu
2b50: 61 74 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67  ates to a string
2b60: 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73   literal that is
2b70: 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73   the SQLite vers
2b80: 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f  ion in the.** fo
2b90: 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77 68 65  rmat "X.Y.Z" whe
2ba0: 72 65 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f  re X is the majo
2bb0: 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  r version number
2bc0: 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a   (always 3 for.*
2bd0: 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64 20 59  * SQLite3) and Y
2be0: 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65   is the minor ve
2bf0: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64  rsion number and
2c00: 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65 61 73   Z is the releas
2c10: 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e  e number.)^.** ^
2c20: 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52  (The [SQLITE_VER
2c30: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70  SION_NUMBER] C p
2c40: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
2c50: 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e  o resolves to an
2c60: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74 68   integer.** with
2c70: 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30   the value (X*10
2c80: 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b  00000 + Y*1000 +
2c90: 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20   Z) where X, Y, 
2ca0: 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20 73 61  and Z are the sa
2cb0: 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73  me.** numbers us
2cc0: 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45  ed in [SQLITE_VE
2cd0: 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65  RSION].)^.** The
2ce0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
2cf0: 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79 20 67  NUMBER for any g
2d00: 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f 66 20  iven release of 
2d10: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
2d20: 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20 74 68  .** be larger th
2d30: 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65 20 66  an the release f
2d40: 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69 73 20  rom which it is 
2d50: 64 65 72 69 76 65 64 2e 20 20 45 69 74 68 65 72  derived.  Either
2d60: 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65   Y will.** be he
2d70: 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20  ld constant and 
2d80: 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Z will be increm
2d90: 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20 59 20  ented or else Y 
2da0: 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e  will be incremen
2db0: 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c  ted.** and Z wil
2dc0: 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20 7a 65  l be reset to ze
2dd0: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20  ro..**.** Since 
2de0: 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20  version 3.6.18, 
2df0: 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f  SQLite source co
2e00: 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72  de has been stor
2e10: 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20  ed in the.** <a 
2e20: 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77  href="http://www
2e30: 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f  .fossil-scm.org/
2e40: 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75  ">Fossil configu
2e50: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e  ration managemen
2e60: 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e  t.** system</a>.
2e70: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
2e80: 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76  URCE_ID macro ev
2e90: 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20  aluates to.** a 
2ea0: 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64 65  string which ide
2eb0: 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69 63  ntifies a partic
2ec0: 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66  ular check-in of
2ed0: 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69   SQLite.** withi
2ee0: 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74  n its configurat
2ef0: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73  ion management s
2f00: 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c  ystem.  ^The SQL
2f10: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a  ITE_SOURCE_ID.**
2f20: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73   string contains
2f30: 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74 69   the date and ti
2f40: 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d  me of the check-
2f50: 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20  in (UTC) and an 
2f60: 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20  SHA1.** hash of 
2f70: 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63  the entire sourc
2f80: 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  e tree..**.** Se
2f90: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2fa0: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a  _libversion()],.
2fb0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  ** [sqlite3_libv
2fc0: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d  ersion_number()]
2fd0: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  , [sqlite3_sourc
2fe0: 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  eid()],.** [sqli
2ff0: 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  te_version()] an
3000: 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65  d [sqlite_source
3010: 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  _id()]..*/.#defi
3020: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
3030: 4e 20 20 20 20 20 20 20 20 22 33 2e 38 2e 31 30  N        "3.8.10
3040: 2e 31 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .1".#define SQLI
3050: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
3060: 52 20 33 30 30 38 30 31 30 0a 23 64 65 66 69 6e  R 3008010.#defin
3070: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
3080: 49 44 20 20 20 20 20 20 22 32 30 31 35 2d 30 35  ID      "2015-05
3090: 2d 30 39 20 31 32 3a 31 34 3a 35 35 20 30 35 62  -09 12:14:55 05b
30a0: 34 62 31 66 32 61 39 33 37 63 30 36 63 39 30 64  4b1f2a937c06c90d
30b0: 62 37 30 63 30 39 38 39 30 30 33 38 66 36 63 39  b70c09890038f6c9
30c0: 38 65 63 34 30 22 0a 0a 2f 2a 0a 2a 2a 20 43 41  8ec40"../*.** CA
30d0: 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
30e0: 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e   Library Version
30f0: 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57   Numbers.** KEYW
3100: 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65  ORDS: sqlite3_ve
3110: 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73  rsion, sqlite3_s
3120: 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68  ourceid.**.** Th
3130: 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70  ese interfaces p
3140: 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20  rovide the same 
3150: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74  information as t
3160: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
3170: 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ON],.** [SQLITE_
3180: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c  VERSION_NUMBER],
3190: 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55   and [SQLITE_SOU
31a0: 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f  RCE_ID] C prepro
31b0: 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a  cessor macros.**
31c0: 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61   but are associa
31d0: 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62  ted with the lib
31e0: 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20  rary instead of 
31f0: 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e  the header file.
3200: 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20    ^(Cautious.** 
3210: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
3220: 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74  t include assert
3230: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
3240: 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69   their applicati
3250: 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20  on to.** verify 
3260: 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75  that values retu
3270: 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e  rned by these in
3280: 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74  terfaces match t
3290: 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20  he macros in.** 
32a0: 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20  the header, and 
32b0: 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74  thus insure that
32c0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32d0: 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
32e0: 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69  with matching li
32f0: 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72  brary and header
3300: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62   files..**.** <b
3310: 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
3320: 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74  ** assert( sqlit
3330: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
3340: 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56  mber()==SQLITE_V
3350: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b  ERSION_NUMBER );
3360: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
3370: 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  mp(sqlite3_sourc
3380: 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55  eid(),SQLITE_SOU
3390: 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a  RCE_ID)==0 );.**
33a0: 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28   assert( strcmp(
33b0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
33c0: 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53  on(),SQLITE_VERS
33d0: 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f  ION)==0 );.** </
33e0: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
33f0: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
3400: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
3410: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
3420: 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65   contains the te
3430: 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45  xt of [SQLITE_VE
3440: 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e  RSION].** macro.
3450: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c    ^The sqlite3_l
3460: 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63  ibversion() func
3470: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70  tion returns a p
3480: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
3490: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
34a0: 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67  version[] string
34b0: 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20   constant.  The 
34c0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
34d0: 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  on().** function
34e0: 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72   is provided for
34f0: 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e   use in DLLs sin
3500: 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75  ce DLL users usu
3510: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65  ally do not have
3520: 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73  .** direct acces
3530: 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73  s to string cons
3540: 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65  tants within the
3550: 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73   DLL.  ^The.** s
3560: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
3570: 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74  n_number() funct
3580: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ion returns an i
3590: 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a  nteger equal to.
35a0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  ** [SQLITE_VERSI
35b0: 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68  ON_NUMBER].  ^Th
35c0: 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  e sqlite3_source
35d0: 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  id() function re
35e0: 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e  turns .** a poin
35f0: 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20  ter to a string 
3600: 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76  constant whose v
3610: 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65  alue is the same
3620: 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c   as the .** [SQL
3630: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43  ITE_SOURCE_ID] C
3640: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
3650: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  cro..**.** See a
3660: 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72  lso: [sqlite_ver
3670: 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  sion()] and [sql
3680: 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d  ite_source_id()]
3690: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
36a0: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
36b0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 53  e3_version[] = S
36c0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 3b 0a 53  QLITE_VERSION;.S
36d0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
36e0: 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
36f0: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62  CALL sqlite3_lib
3700: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53  version(void);.S
3710: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
3720: 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
3730: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 6f 75  CALL sqlite3_sou
3740: 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c  rceid(void);.SQL
3750: 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
3760: 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
3770: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
3780: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  mber(void);../*.
3790: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
37a0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f  -Time Library Co
37b0: 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  mpilation Option
37c0: 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a  s Diagnostics.**
37d0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37e0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
37f0: 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  sed() function r
3800: 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a  eturns 0 or 1 .*
3810: 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65  * indicating whe
3820: 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69  ther the specifi
3830: 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65  ed option was de
3840: 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d  fined at .** com
3850: 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65  pile time.  ^The
3860: 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20   SQLITE_ prefix 
3870: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66  may be omitted f
3880: 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69  rom the .** opti
3890: 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74  on name passed t
38a0: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  o sqlite3_compil
38b0: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20  eoption_used(). 
38c0: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
38d0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
38e0: 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f  on_get() functio
38f0: 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69  n allows iterati
3900: 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c  ng.** over the l
3910: 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74  ist of options t
3920: 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64  hat were defined
3930: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
3940: 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67   by.** returning
3950: 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c   the N-th compil
3960: 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74  e time option st
3970: 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20  ring.  ^If N is 
3980: 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a  out of range,.**
3990: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
39a0: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74  option_get() ret
39b0: 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
39c0: 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ter.  ^The SQLIT
39d0: 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73  E_ .** prefix is
39e0: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e   omitted from an
39f0: 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  y strings return
3a00: 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
3a10: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
3a20: 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75  get()..**.** ^Su
3a30: 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69  pport for the di
3a40: 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f  agnostic functio
3a50: 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ns sqlite3_compi
3a60: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a  leoption_used().
3a70: 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
3a80: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
3a90: 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  () may be omitte
3aa0: 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20  d by specifying 
3ab0: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
3ac0: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
3ad0: 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e  ON_DIAGS] option
3ae0: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
3af0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
3b00: 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  : SQL functions 
3b10: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
3b20: 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e  ption_used()] an
3b30: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  d.** [sqlite_com
3b40: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
3b50: 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69  ] and the [compi
3b60: 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d  le_options pragm
3b70: 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  a]..*/.#ifndef S
3b80: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49  QLITE_OMIT_COMPI
3b90: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53  LEOPTION_DIAGS.S
3ba0: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
3bb0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
3bc0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
3bd0: 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68  on_used(const ch
3be0: 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53  ar *zOptName);.S
3bf0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
3c00: 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
3c10: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d  CALL sqlite3_com
3c20: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69  pileoption_get(i
3c30: 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt N);.#endif../
3c40: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
3c50: 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54 68  est To See If Th
3c60: 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68 72  e Library Is Thr
3c70: 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54  eadsafe.**.** ^T
3c80: 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  he sqlite3_threa
3c90: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
3ca0: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66   returns zero if
3cb0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
3cc0: 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69  SQLite was compi
3cd0: 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e  led with mutexin
3ce0: 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64  g code omitted d
3cf0: 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51  ue to the.** [SQ
3d00: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
3d10: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
3d20: 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74  tion being set t
3d30: 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  o 0..**.** SQLit
3d40: 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65  e can be compile
3d50: 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75  d with or withou
3d60: 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e  t mutexes.  When
3d70: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
3d80: 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72  THREADSAFE] C pr
3d90: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
3da0: 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65   is 1 or 2, mute
3db0: 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
3dc0: 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73  ed and SQLite is
3dd0: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68   threadsafe.  Wh
3de0: 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  en the.** [SQLIT
3df0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
3e00: 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68  cro is 0, .** th
3e10: 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d  e mutexes are om
3e20: 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20  itted.  Without 
3e30: 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20  the mutexes, it 
3e40: 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74  is not safe.** t
3e50: 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e  o use SQLite con
3e60: 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d  currently from m
3e70: 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72  ore than one thr
3e80: 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c  ead..**.** Enabl
3e90: 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75  ing mutexes incu
3ea0: 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20  rs a measurable 
3eb0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61  performance pena
3ec0: 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70  lty..** So if sp
3ed0: 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74  eed is of utmost
3ee0: 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20   importance, it 
3ef0: 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64  makes sense to d
3f00: 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75  isable.** the mu
3f10: 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20  texes.  But for 
3f20: 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20  maximum safety, 
3f30: 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62  mutexes should b
3f40: 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54  e enabled..** ^T
3f50: 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  he default behav
3f60: 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78  ior is for mutex
3f70: 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64  es to be enabled
3f80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
3f90: 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
3fa0: 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61  ed by an applica
3fb0: 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72  tion to make sur
3fc0: 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65  e that the.** ve
3fd0: 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20  rsion of SQLite 
3fe0: 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69  that it is linki
3ff0: 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63  ng against was c
4000: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
4010: 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74  the desired sett
4020: 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ing of the [SQLI
4030: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
4040: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  acro..**.** This
4050: 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20   interface only 
4060: 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63  reports on the c
4070: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65  ompile-time mute
4080: 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20  x setting.** of 
4090: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
40a0: 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49  ADSAFE] flag.  I
40b0: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
40c0: 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c  iled with.** SQL
40d0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
40e0: 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65   or =2 then mute
40f0: 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  xes are enabled 
4100: 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a  by default but.*
4110: 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f  * can be fully o
4120: 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61  r partially disa
4130: 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c  bled using a cal
4140: 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  l to [sqlite3_co
4150: 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20  nfig()].** with 
4160: 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54  the verbs [SQLIT
4170: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
4180: 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  HREAD], [SQLITE_
4190: 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
41a0: 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49  AD],.** or [SQLI
41b0: 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
41c0: 49 5a 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65  IZED].  ^(The re
41d0: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
41e0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
41f0: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
4200: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
4210: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
4220: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
4230: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
4240: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
4250: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
4260: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
4270: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
4280: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
4290: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
42a0: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
42b0: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
42c0: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
42d0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
42e0: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
42f0: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
4300: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
4310: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
4320: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
4330: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
4340: 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
4350: 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74  TDCALL sqlite3_t
4360: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b  hreadsafe(void);
4370: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4380: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
4390: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20  ction Handle.** 
43a0: 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62  KEYWORDS: {datab
43b0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20  ase connection} 
43c0: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
43d0: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63  tions}.**.** Eac
43e0: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  h open SQLite da
43f0: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73  tabase is repres
4400: 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74  ented by a point
4410: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
4420: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71  e of.** the opaq
4430: 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d  ue structure nam
4440: 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49  ed "sqlite3".  I
4450: 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74  t is useful to t
4460: 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74  hink of an sqlit
4470: 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73  e3.** pointer as
4480: 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65   an object.  The
4490: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
44a0: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
44b0: 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  16()], and.** [s
44c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
44d0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ] interfaces are
44e0: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72   its constructor
44f0: 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  s, and [sqlite3_
4500: 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20  close()].** and 
4510: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76  [sqlite3_close_v
4520: 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65 73  2()] are its des
4530: 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65  tructors.  There
4540: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a   are many other.
4550: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28 73  ** interfaces (s
4560: 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74  uch as.** [sqlit
4570: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
4580: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
4590: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61  e_function()], a
45a0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
45b0: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74  usy_timeout()] t
45c0: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
45d0: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
45e0: 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ds on an.** sqli
45f0: 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74  te3 object..*/.t
4600: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
4610: 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a  lite3 sqlite3;..
4620: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4630: 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54  64-Bit Integer T
4640: 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
4650: 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  : sqlite_int64 s
4660: 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a  qlite_uint64.**.
4670: 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65  ** Because there
4680: 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61   is no cross-pla
4690: 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65  tform way to spe
46a0: 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65  cify 64-bit inte
46b0: 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c  ger types.** SQL
46c0: 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70  ite includes typ
46d0: 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74  edefs for 64-bit
46e0: 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69   signed and unsi
46f0: 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a  gned integers..*
4700: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
4710: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
4720: 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68  e3_uint64 are th
4730: 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65  e preferred type
4740: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a   definitions..**
4750: 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36   The sqlite_int6
4760: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
4770: 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75  t64 types are su
4780: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b  pported for back
4790: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69  wards.** compati
47a0: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  bility only..**.
47b0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
47c0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
47d0: 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  _int64 types can
47e0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
47f0: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
4800: 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37   -92233720368547
4810: 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33  75808 and +92233
4820: 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69  72036854775807 i
4830: 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a  nclusive.  ^The.
4840: 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  ** sqlite3_uint6
4850: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
4860: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
4870: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
4880: 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  es .** between 0
4890: 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37   and +1844674407
48a0: 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75  3709551615 inclu
48b0: 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  sive..*/.#ifdef 
48c0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
48d0: 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49  E.  typedef SQLI
48e0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
48f0: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
4900: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53  pedef unsigned S
4910: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
4920: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
4930: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
4940: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
4950: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
4960: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
4970: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
4980: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
4990: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
49a0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
49b0: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
49c0: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
49d0: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
49e0: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
49f0: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
4a00: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79  int64;.#endif.ty
4a10: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74  pedef sqlite_int
4a20: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64 sqlite3_int64
4a30: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  ;.typedef sqlite
4a40: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
4a50: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49  uint64;../*.** I
4a60: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  f compiling for 
4a70: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74  a processor that
4a80: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20   lacks floating 
4a90: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a  point support,.*
4aa0: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74  * substitute int
4ab0: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e  eger for floatin
4ac0: 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64  g-point..*/.#ifd
4ad0: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46  ef SQLITE_OMIT_F
4ae0: 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20  LOATING_POINT.# 
4af0: 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71  define double sq
4b00: 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64  lite3_int64.#end
4b10: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
4b20: 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61  EF: Closing A Da
4b30: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
4b40: 6e 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a  n.** DESTRUCTOR:
4b50: 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
4b60: 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  The sqlite3_clos
4b70: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
4b80: 63 6c 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69  close_v2() routi
4b90: 6e 65 73 20 61 72 65 20 64 65 73 74 72 75 63 74  nes are destruct
4ba0: 6f 72 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ors.** for the [
4bb0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e  sqlite3] object.
4bc0: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
4bd0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
4be0: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
4bf0: 76 32 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c  v2() return [SQL
4c00: 49 54 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68  ITE_OK] if.** th
4c10: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
4c20: 63 74 20 69 73 20 73 75 63 63 65 73 73 66 75 6c  ct is successful
4c30: 6c 79 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64  ly destroyed and
4c40: 20 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a   all associated.
4c50: 2a 2a 20 72 65 73 6f 75 72 63 65 73 20 61 72 65  ** resources are
4c60: 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a   deallocated..**
4c70: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
4c80: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
4c90: 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
4ca0: 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70  th unfinalized p
4cb0: 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
4cc0: 6d 65 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73  ments or unfinis
4cd0: 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  hed sqlite3_back
4ce0: 75 70 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  up objects then 
4cf0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a  sqlite3_close().
4d00: 2a 2a 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68  ** will leave th
4d10: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
4d20: 63 74 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72  ction open and r
4d30: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
4d40: 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  SY]..** ^If sqli
4d50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
4d60: 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e  s called with un
4d70: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
4d80: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  ed statements.**
4d90: 20 61 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68   and/or unfinish
4da0: 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  ed sqlite3_backu
4db0: 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ps, then the dat
4dc0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
4dd0: 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75   becomes.** an u
4de0: 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22  nusable "zombie"
4df0: 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f   which will auto
4e00: 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61  matically be dea
4e10: 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68  llocated when th
4e20: 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72  e.** last prepar
4e30: 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ed statement is 
4e40: 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65  finalized or the
4e50: 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61   last sqlite3_ba
4e60: 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73  ckup is.** finis
4e70: 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65  hed.  The sqlite
4e80: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74  3_close_v2() int
4e90: 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64  erface is intend
4ea0: 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a  ed for use with.
4eb0: 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65  ** host language
4ec0: 73 20 74 68 61 74 20 61 72 65 20 67 61 72 62 61  s that are garba
4ed0: 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e  ge collected, an
4ee0: 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 64 65  d where the orde
4ef0: 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65  r in which.** de
4f00: 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 63 61  structors are ca
4f10: 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 61 72  lled is arbitrar
4f20: 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  y..**.** Applica
4f30: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71  tions should [sq
4f40: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
4f50: 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b   finalize] all [
4f60: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
4f70: 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  nts],.** [sqlite
4f80: 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63  3_blob_close | c
4f90: 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20  lose] all [BLOB 
4fa0: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a  handles], and .*
4fb0: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
4fc0: 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73  p_finish | finis
4fd0: 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  h] all [sqlite3_
4fe0: 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20  backup] objects 
4ff0: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69  associated.** wi
5000: 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  th the [sqlite3]
5010: 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f   object prior to
5020: 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63   attempting to c
5030: 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e  lose the object.
5040: 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33    ^If.** sqlite3
5050: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63  _close_v2() is c
5060: 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61  alled on a [data
5070: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
5080: 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a   that still has.
5090: 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b  ** outstanding [
50a0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
50b0: 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64  nts], [BLOB hand
50c0: 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20  les], and/or.** 
50d0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
50e0: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74   objects then it
50f0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
5100: 5f 4f 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61  _OK] and the dea
5110: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
5120: 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66  resources is def
5130: 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20  erred until all 
5140: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
5150: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e  ents], [BLOB han
5160: 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73  dles],.** and [s
5170: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
5180: 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20  bjects are also 
5190: 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a  destroyed..**.**
51a0: 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33   ^If an [sqlite3
51b0: 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74  ] object is dest
51c0: 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72  royed while a tr
51d0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65  ansaction is ope
51e0: 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61  n,.** the transa
51f0: 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74  ction is automat
5200: 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
5210: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20  ck..**.** The C 
5220: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
5230: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
5240: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
5250: 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73  se_v2(C)].** mus
5260: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
5270: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72  LL.** pointer or
5280: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
5290: 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74  ject pointer obt
52a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
52b0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
52c0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
52d0: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
52e0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
52f0: 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  nd not previousl
5300: 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61  y closed..** ^Ca
5310: 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c  lling sqlite3_cl
5320: 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ose() or sqlite3
5330: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68  _close_v2() with
5340: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
5350: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  ** argument is a
5360: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
5370: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
5380: 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
5390: 4c 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  L sqlite3_close(
53a0: 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
53b0: 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
53c0: 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
53d0: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
53e0: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
53f0: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
5400: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
5410: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
5420: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
5430: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
5440: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
5450: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
5460: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
5470: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
5480: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
5490: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
54a0: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
54b0: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
54c0: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
54d0: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
54e0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48  nterface.** METH
54f0: 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OD: sqlite3.**.*
5500: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
5510: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ec() interface i
5520: 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20  s a convenience 
5530: 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
5540: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
5550: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
5560: 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20  e3_step()], and 
5570: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
5580: 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c  e()],.** that al
5590: 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74  lows an applicat
55a0: 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69  ion to run multi
55b0: 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  ple statements o
55c0: 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74  f SQL.** without
55d0: 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61   having to use a
55e0: 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20   lot of C code. 
55f0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
5600: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
5610: 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f  face runs zero o
5620: 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63  r more UTF-8 enc
5630: 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c  oded,.** semicol
5640: 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20  on-separate SQL 
5650: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
5660: 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61  d into its 2nd a
5670: 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74  rgument,.** in t
5680: 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68  he context of th
5690: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
56a0: 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69  ection] passed i
56b0: 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20  n as its 1st.** 
56c0: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74  argument.  ^If t
56d0: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
56e0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20  tion of the 3rd 
56f0: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
5700: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
5710: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
5720: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f  it is invoked fo
5730: 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f  r each result ro
5740: 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20  w.** coming out 
5750: 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64  of the evaluated
5760: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
5770: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
5780: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
5790: 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61  3_exec() is rela
57a0: 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74  yed through to t
57b0: 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20  he 1st argument 
57c0: 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62  of each.** callb
57d0: 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20  ack invocation. 
57e0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
57f0: 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  k pointer to sql
5800: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
5810: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20  s NULL, then no 
5820: 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72  callback is ever
5830: 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73   invoked and res
5840: 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20  ult rows are.** 
5850: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
5860: 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
5870: 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74  rs while evaluat
5880: 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74  ing the SQL stat
5890: 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e  ements passed in
58a0: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
58b0: 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75  ec(), then execu
58c0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72  tion of the curr
58d0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74  ent statement st
58e0: 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65  ops and.** subse
58f0: 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73  quent statements
5900: 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e   are skipped.  ^
5910: 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  If the 5th param
5920: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
5930: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  exec().** is not
5940: 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65   NULL then any e
5950: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20  rror message is 
5960: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
5970: 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ory obtained.** 
5980: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
5990: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73  lloc()] and pass
59a0: 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20  ed back through 
59b0: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
59c0: 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d  r..** To avoid m
59d0: 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65  emory leaks, the
59e0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
59f0: 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69  uld invoke [sqli
5a00: 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f  te3_free()].** o
5a10: 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
5a20: 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
5a30: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
5a40: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a   parameter of.**
5a50: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
5a60: 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72  () after the err
5a70: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
5a80: 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e  g is no longer n
5a90: 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  eeded..** ^If th
5aa0: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
5ab0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
5ac0: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  ) is not NULL an
5ad0: 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
5ae0: 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  ccur, then sqlit
5af0: 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74  e3_exec() sets t
5b00: 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74  he pointer in it
5b10: 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  s 5th parameter 
5b20: 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72  to.** NULL befor
5b30: 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
5b40: 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65  ** ^If an sqlite
5b50: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
5b60: 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
5b70: 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ro, the sqlite3_
5b80: 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  exec().** routin
5b90: 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  e returns SQLITE
5ba0: 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69  _ABORT without i
5bb0: 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c  nvoking the call
5bc0: 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a  back again and.*
5bd0: 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e  * without runnin
5be0: 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  g any subsequent
5bf0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
5c00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20  .**.** ^The 2nd 
5c10: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
5c20: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
5c30: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
5c40: 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
5c50: 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
5c60: 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68  the result.  ^Th
5c70: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
5c80: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
5c90: 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  ec().** callback
5ca0: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
5cb0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
5cc0: 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20  ngs obtained as 
5cd0: 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  if from.** [sqli
5ce0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
5cf0: 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68  )], one for each
5d00: 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e   column.  ^If an
5d10: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a   element of a.**
5d20: 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e   result row is N
5d30: 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72  ULL then the cor
5d40: 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e  responding strin
5d50: 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  g pointer for th
5d60: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  e.** sqlite3_exe
5d70: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  c() callback is 
5d80: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
5d90: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
5da0: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c  nt to the.** sql
5db0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
5dc0: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
5dd0: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
5de0: 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61  strings where ea
5df0: 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72  ch.** entry repr
5e00: 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20  esents the name 
5e10: 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  of corresponding
5e20: 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61   result column a
5e30: 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
5e40: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
5e50: 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a  mn_name()]..**.*
5e60: 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61  * ^If the 2nd pa
5e70: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
5e80: 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e  e3_exec() is a N
5e90: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70  ULL pointer, a p
5ea0: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20  ointer.** to an 
5eb0: 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72  empty string, or
5ec0: 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20   a pointer that 
5ed0: 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68  contains only wh
5ee0: 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20  itespace and/or 
5ef0: 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73  .** SQL comments
5f00: 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74  , then no SQL st
5f10: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61  atements are eva
5f20: 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64  luated and the d
5f30: 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f  atabase.** is no
5f40: 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  t changed..**.**
5f50: 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a   Restrictions:.*
5f60: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
5f70: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
5f80: 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68  n must insure th
5f90: 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d  at the 1st param
5fa0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
5fb0: 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69  exec().**      i
5fc0: 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70  s a valid and op
5fd0: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
5fe0: 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69  nection]..** <li
5ff0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
6000: 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  n must not close
6010: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
6020: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
6030: 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  fied by.**      
6040: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
6050: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
6060: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
6070: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
6080: 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  ing..** <li> The
6090: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
60a0: 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  t not modify the
60b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
60c0: 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  ext passed into.
60d0: 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20  **      the 2nd 
60e0: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
60f0: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
6100: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
6110: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
6120: 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ul>.*/.SQLITE_
6130: 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
6140: 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
6150: 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  xec(.  sqlite3*,
6160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6170: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6180: 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
6190: 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
61a0: 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20   char *sql,     
61b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
61c0: 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20        /* SQL to 
61d0: 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
61e0: 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b    int (*callback
61f0: 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72  )(void*,int,char
6200: 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20  **,char**),  /* 
6210: 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  Callback functio
6220: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20  n */.  void *,  
6230: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6240: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6250: 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e    /* 1st argumen
6260: 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f  t to callback */
6270: 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67  .  char **errmsg
6280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6290: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
62a0: 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
62b0: 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f  en here */.);../
62c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
62d0: 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b  esult Codes.** K
62e0: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
62f0: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
6300: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
6310: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
6320: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
6330: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
6340: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
6350: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
6360: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63   to indicate suc
6370: 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e  cess or failure.
6380: 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72  .**.** New error
6390: 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64   codes may be ad
63a0: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65  ded in future ve
63b0: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
63c0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
63d0: 3a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  : [extended resu
63e0: 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69  lt code definiti
63f0: 6f 6e 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ons].*/.#define 
6400: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
6410: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
6420: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
6430: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
6440: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
6450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
6460: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
6470: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
6480: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
6490: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
64a0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
64b0: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
64c0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
64d0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
64e0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
64f0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
6500: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
6510: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
6520: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
6530: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
6540: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
6550: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
6560: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6570: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
6580: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
6590: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
65a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
65b0: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
65c0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
65d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
65e0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
65f0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
6600: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
6610: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
6620: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6630: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
6640: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
6650: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
6660: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
6670: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
6680: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
6690: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
66a0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
66b0: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
66c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
66d0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
66e0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
66f0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
6700: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
6710: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
6720: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
6730: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
6740: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
6750: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
6760: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
6770: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
6780: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
6790: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
67a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
67b0: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
67c0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
67d0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
67e0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
67f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6800: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
6810: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
6820: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
6830: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
6840: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
6850: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
6860: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
6870: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
6880: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
6890: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
68a0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
68b0: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
68c0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
68d0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
68e0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
68f0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
6900: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
6910: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
6920: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
6930: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
6940: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
6950: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
6960: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
6970: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
6980: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
6990: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
69a0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
69b0: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
69c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69d0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
69e0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
69f0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
6a00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
6a10: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
6a20: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
6a30: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
6a40: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
6a50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
6a60: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
6a70: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
6a80: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
6a90: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
6aa0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
6ab0: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
6ac0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
6ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
6ae0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
6af0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
6b00: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
6b10: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
6b20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
6b30: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
6b40: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
6b50: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
6b60: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
6b70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
6b80: 43 45 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20  CE      27   /* 
6b90: 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72  Notifications fr
6ba0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
6bb0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6bc0: 54 45 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32  TE_WARNING     2
6bd0: 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20  8   /* Warnings 
6be0: 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67  from sqlite3_log
6bf0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
6c00: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
6c10: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
6c20: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
6c30: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
6c40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6c50: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
6c60: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
6c70: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
6c80: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
6c90: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
6ca0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
6cb0: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
6cc0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
6cd0: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
6ce0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ded result code 
6cf0: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
6d00: 2a 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c  ** In its defaul
6d10: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  t configuration,
6d20: 20 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74   SQLite API rout
6d30: 69 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20  ines return one 
6d40: 6f 66 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a  of 30 integer.**
6d50: 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e   [result codes].
6d60: 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72    However, exper
6d70: 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20  ience has shown 
6d80: 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20  that many of.** 
6d90: 74 68 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64  these result cod
6da0: 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73  es are too coars
6db0: 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79  e-grained.  They
6dc0: 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20   do not provide 
6dd0: 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72  as.** much infor
6de0: 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f  mation about pro
6df0: 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d  blems as program
6e00: 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e  mers might like.
6e10: 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74    In an effort t
6e20: 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69  o.** address thi
6e30: 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e  s, newer version
6e40: 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72  s of SQLite (ver
6e50: 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c  sion 3.3.8 and l
6e60: 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a  ater) include.**
6e70: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64   support for add
6e80: 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63  itional result c
6e90: 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64  odes that provid
6ea0: 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20  e more detailed 
6eb0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61  information.** a
6ec0: 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65  bout errors. The
6ed0: 73 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  se [extended res
6ee0: 75 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65  ult codes] are e
6ef0: 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c  nabled or disabl
6f00: 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64  ed.** on a per d
6f10: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
6f20: 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74  on basis using t
6f30: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  he.** [sqlite3_e
6f40: 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
6f50: 6f 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72  odes()] API.  Or
6f60: 2c 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63  , the extended c
6f70: 6f 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d  ode for.** the m
6f80: 6f 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72  ost recent error
6f90: 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
6fa0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
6fb0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
6fc0: 6f 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  ode()]..*/.#defi
6fd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
6fe0: 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
6ff0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
7000: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
7010: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
7020: 48 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20  HORT_READ       
7030: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
7040: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
7050: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52   SQLITE_IOERR_WR
7060: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
7070: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
7080: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
7090: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59  SQLITE_IOERR_FSY
70a0: 4e 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28  NC             (
70b0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
70c0: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
70d0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f  QLITE_IOERR_DIR_
70e0: 46 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53  FSYNC         (S
70f0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35  QLITE_IOERR | (5
7100: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7110: 4c 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43  LITE_IOERR_TRUNC
7120: 41 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51  ATE          (SQ
7130: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c  LITE_IOERR | (6<
7140: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7150: 49 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20  ITE_IOERR_FSTAT 
7160: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
7170: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c  ITE_IOERR | (7<<
7180: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
7190: 54 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20  TE_IOERR_UNLOCK 
71a0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
71b0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38  TE_IOERR | (8<<8
71c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
71d0: 45 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20  E_IOERR_RDLOCK  
71e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
71f0: 45 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29  E_IOERR | (9<<8)
7200: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7210: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20  _IOERR_DELETE   
7220: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7230: 5f 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29  _IOERR | (10<<8)
7240: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7250: 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20  _IOERR_BLOCKED  
7260: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7270: 5f 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29  _IOERR | (11<<8)
7280: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7290: 5f 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20  _IOERR_NOMEM    
72a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
72b0: 5f 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29  _IOERR | (12<<8)
72c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
72d0: 5f 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20  _IOERR_ACCESS   
72e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
72f0: 5f 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29  _IOERR | (13<<8)
7300: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7310: 5f 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45  _IOERR_CHECKRESE
7320: 52 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45  RVEDLOCK (SQLITE
7330: 5f 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29  _IOERR | (14<<8)
7340: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7350: 5f 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20  _IOERR_LOCK     
7360: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7370: 5f 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29  _IOERR | (15<<8)
7380: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7390: 5f 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20  _IOERR_CLOSE    
73a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
73b0: 5f 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29  _IOERR | (16<<8)
73c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
73d0: 5f 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45  _IOERR_DIR_CLOSE
73e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
73f0: 5f 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29  _IOERR | (17<<8)
7400: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7410: 5f 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20  _IOERR_SHMOPEN  
7420: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7430: 5f 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29  _IOERR | (18<<8)
7440: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7450: 5f 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20  _IOERR_SHMSIZE  
7460: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7470: 5f 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29  _IOERR | (19<<8)
7480: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7490: 5f 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20  _IOERR_SHMLOCK  
74a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
74b0: 5f 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29  _IOERR | (20<<8)
74c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
74d0: 5f 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20  _IOERR_SHMMAP   
74e0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
74f0: 5f 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29  _IOERR | (21<<8)
7500: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7510: 5f 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20  _IOERR_SEEK     
7520: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7530: 5f 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29  _IOERR | (22<<8)
7540: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7550: 5f 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f  _IOERR_DELETE_NO
7560: 45 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45  ENT      (SQLITE
7570: 5f 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29  _IOERR | (23<<8)
7580: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7590: 5f 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20  _IOERR_MMAP     
75a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
75b0: 5f 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29  _IOERR | (24<<8)
75c0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
75d0: 5f 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41  _IOERR_GETTEMPPA
75e0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
75f0: 5f 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29  _IOERR | (25<<8)
7600: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7610: 5f 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20  _IOERR_CONVPATH 
7620: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7630: 5f 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29  _IOERR | (26<<8)
7640: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7650: 5f 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41  _LOCKED_SHAREDCA
7660: 43 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45  CHE      (SQLITE
7670: 5f 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38  _LOCKED |  (1<<8
7680: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7690: 45 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20  E_BUSY_RECOVERY 
76a0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
76b0: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c  E_BUSY   |  (1<<
76c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
76d0: 54 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54  TE_BUSY_SNAPSHOT
76e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
76f0: 54 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c  TE_BUSY   |  (2<
7700: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7710: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54  ITE_CANTOPEN_NOT
7720: 45 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c  EMPDIR      (SQL
7730: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
7740: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
7750: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49  QLITE_CANTOPEN_I
7760: 53 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53  SDIR          (S
7770: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
7780: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
7790: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
77a0: 5f 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20  _FULLPATH       
77b0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
77c0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
77d0: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
77e0: 45 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20  EN_CONVPATH     
77f0: 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50    (SQLITE_CANTOP
7800: 45 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  EN | (4<<8)).#de
7810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
7820: 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20  UPT_VTAB        
7830: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52      (SQLITE_CORR
7840: 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  UPT | (1<<8)).#d
7850: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
7860: 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20  DONLY_RECOVERY  
7870: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
7880: 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a  DONLY | (1<<8)).
7890: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
78a0: 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b  EADONLY_CANTLOCK
78b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
78c0: 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29  EADONLY | (2<<8)
78d0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
78e0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41  _READONLY_ROLLBA
78f0: 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  CK       (SQLITE
7900: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c  _READONLY | (3<<
7910: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
7920: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f  TE_READONLY_DBMO
7930: 56 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  VED        (SQLI
7940: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34  TE_READONLY | (4
7950: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7960: 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42  LITE_ABORT_ROLLB
7970: 41 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51  ACK          (SQ
7980: 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c  LITE_ABORT | (2<
7990: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
79a0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43  ITE_CONSTRAINT_C
79b0: 48 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c  HECK        (SQL
79c0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
79d0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
79e0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
79f0: 4e 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20  NT_COMMITHOOK   
7a00: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
7a10: 4e 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  NT | (2<<8)).#de
7a20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
7a30: 54 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45  TRAINT_FOREIGNKE
7a40: 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53  Y   (SQLITE_CONS
7a50: 54 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29  TRAINT | (3<<8))
7a60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7a70: 43 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54  CONSTRAINT_FUNCT
7a80: 49 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f  ION     (SQLITE_
7a90: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c  CONSTRAINT | (4<
7aa0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7ab0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e  ITE_CONSTRAINT_N
7ac0: 4f 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c  OTNULL      (SQL
7ad0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
7ae0: 20 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (5<<8)).#define
7af0: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
7b00: 4e 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20  NT_PRIMARYKEY   
7b10: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
7b20: 4e 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  NT | (6<<8)).#de
7b30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
7b40: 54 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20  TRAINT_TRIGGER  
7b50: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53      (SQLITE_CONS
7b60: 54 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29  TRAINT | (7<<8))
7b70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7b80: 43 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55  CONSTRAINT_UNIQU
7b90: 45 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  E       (SQLITE_
7ba0: 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c  CONSTRAINT | (8<
7bb0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7bc0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56  ITE_CONSTRAINT_V
7bd0: 54 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c  TAB         (SQL
7be0: 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c  ITE_CONSTRAINT |
7bf0: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
7c00: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
7c10: 4e 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20  NT_ROWID        
7c20: 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49  (SQLITE_CONSTRAI
7c30: 4e 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65  NT |(10<<8)).#de
7c40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
7c50: 43 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20  CE_RECOVER_WAL  
7c60: 20 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49      (SQLITE_NOTI
7c70: 43 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  CE | (1<<8)).#de
7c80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49  fine SQLITE_NOTI
7c90: 43 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42  CE_RECOVER_ROLLB
7ca0: 41 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49  ACK (SQLITE_NOTI
7cb0: 43 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65  CE | (2<<8)).#de
7cc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e  fine SQLITE_WARN
7cd0: 49 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20  ING_AUTOINDEX   
7ce0: 20 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e      (SQLITE_WARN
7cf0: 49 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  ING | (1<<8)).#d
7d00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54  efine SQLITE_AUT
7d10: 48 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20  H_USER          
7d20: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54       (SQLITE_AUT
7d30: 48 20 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a  H | (1<<8))../*.
7d40: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
7d50: 67 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e  gs For File Open
7d60: 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a   Operations.**.*
7d70: 2a 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75  * These bit valu
7d80: 65 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  es are intended 
7d90: 66 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a  for use in the.*
7da0: 2a 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  * 3rd parameter 
7db0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
7dc0: 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72  open_v2()] inter
7dd0: 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74  face and.** in t
7de0: 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
7df0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
7e00: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68  _vfs.xOpen] meth
7e10: 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  od..*/.#define S
7e20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
7e30: 4e 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30  NLY         0x00
7e40: 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f  000001  /* Ok fo
7e50: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
7e60: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
7e70: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
7e80: 52 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30  RITE        0x00
7e90: 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f  000002  /* Ok fo
7ea0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
7eb0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
7ec0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
7ed0: 45 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  E           0x00
7ee0: 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f  000004  /* Ok fo
7ef0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
7f00: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
7f10: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
7f20: 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30  EONCLOSE    0x00
7f30: 30 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f  000008  /* VFS o
7f40: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
7f50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
7f60: 53 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30  SIVE        0x00
7f70: 30 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f  000010  /* VFS o
7f80: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
7f90: 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50  QLITE_OPEN_AUTOP
7fa0: 52 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30  ROXY        0x00
7fb0: 30 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f  000020  /* VFS o
7fc0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
7fd0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20  QLITE_OPEN_URI  
7fe0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
7ff0: 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f  000040  /* Ok fo
8000: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8010: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8020: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52  QLITE_OPEN_MEMOR
8030: 59 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30  Y           0x00
8040: 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f  000080  /* Ok fo
8050: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8060: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8070: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
8080: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
8090: 30 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f  000100  /* VFS o
80a0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
80b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
80c0: 44 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30  DB          0x00
80d0: 30 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f  000200  /* VFS o
80e0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
80f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
8100: 49 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30  IENT_DB     0x00
8110: 30 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f  000400  /* VFS o
8120: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8130: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
8140: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
8150: 30 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f  000800  /* VFS o
8160: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8170: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
8180: 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30  JOURNAL     0x00
8190: 30 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  001000  /* VFS o
81a0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
81b0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
81c0: 55 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30  URNAL       0x00
81d0: 30 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  002000  /* VFS o
81e0: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
81f0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
8200: 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30  R_JOURNAL   0x00
8210: 30 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  004000  /* VFS o
8220: 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
8230: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
8240: 45 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30  EX          0x00
8250: 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  008000  /* Ok fo
8260: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8270: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8280: 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
8290: 55 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30  UTEX        0x00
82a0: 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  010000  /* Ok fo
82b0: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
82c0: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
82d0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
82e0: 44 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30  DCACHE      0x00
82f0: 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  020000  /* Ok fo
8300: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8310: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8320: 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41  QLITE_OPEN_PRIVA
8330: 54 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30  TECACHE     0x00
8340: 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f  040000  /* Ok fo
8350: 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
8360: 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  2() */.#define S
8370: 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20  QLITE_OPEN_WAL  
8380: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
8390: 30 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f  080000  /* VFS o
83a0: 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72  nly */../* Reser
83b0: 76 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20  ved:            
83c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
83d0: 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a  0F00000 */../*.*
83e0: 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69  * CAPI3REF: Devi
83f0: 63 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69  ce Characteristi
8400: 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65  cs.**.** The xDe
8410: 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74  viceCharacterist
8420: 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ics method of th
8430: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
8440: 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74  thods].** object
8450: 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65   returns an inte
8460: 67 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76  ger which is a v
8470: 65 63 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a  ector of these.*
8480: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
8490: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
84a0: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
84b0: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
84c0: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
84d0: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
84e0: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
84f0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
8500: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
8510: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8520: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
8530: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
8540: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
8550: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8560: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8570: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8580: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
8590: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
85a0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
85b0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
85c0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
85d0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
85e0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
85f0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8600: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
8610: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8620: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
8630: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
8640: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
8650: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8660: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8670: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8680: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
8690: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
86a0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
86b0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
86c0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
86d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
86e0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
86f0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8700: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
8710: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
8720: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
8730: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
8740: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
8750: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
8760: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
8770: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8780: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
8790: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
87a0: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
87b0: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
87c0: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
87d0: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
87e0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
87f0: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
8800: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
8810: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
8820: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
8830: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
8840: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
8850: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
8860: 65 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  e unchanged.  Th
8870: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55  e SQLITE_IOCAP_U
8880: 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f  NDELETABLE_WHEN_
8890: 4f 50 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64  OPEN.** flag ind
88a0: 69 63 61 74 65 20 74 68 61 74 20 61 20 66 69 6c  icate that a fil
88b0: 65 20 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65  e cannot be dele
88c0: 74 65 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20  ted when open.  
88d0: 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f  The.** SQLITE_IO
88e0: 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c  CAP_IMMUTABLE fl
88f0: 61 67 20 69 6e 64 69 63 61 74 65 73 20 74 68 61  ag indicates tha
8900: 74 20 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e  t the file is on
8910: 0a 2a 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65  .** read-only me
8920: 64 69 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62  dia and cannot b
8930: 65 20 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62  e changed even b
8940: 79 20 70 72 6f 63 65 73 73 65 73 20 77 69 74 68  y processes with
8950: 0a 2a 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69  .** elevated pri
8960: 76 69 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66  vileges..*/.#def
8970: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
8980: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
8990: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
89a0: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
89b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
89c0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
89d0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
89e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
89f0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
8a00: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
8a10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8a20: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
8a30: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
8a40: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
8a50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8a60: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
8a70: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
8a80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
8a90: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
8aa0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
8ab0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
8ac0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8ad0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
8ae0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
8af0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
8b00: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
8b10: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8b20: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
8b30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
8b40: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
8b50: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
8b60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
8b70: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
8b80: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
8b90: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
8ba0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
8bb0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
8bc0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
8bd0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
8be0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
8bf0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
8c00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8c10: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
8c20: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
8c30: 30 30 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53  001000.#define S
8c40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55  QLITE_IOCAP_IMMU
8c50: 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
8c60: 20 20 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f     0x00002000../
8c70: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
8c80: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
8c90: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
8ca0: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
8cb0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
8cc0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
8cd0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
8ce0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
8cf0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
8d00: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
8d10: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
8d20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8d30: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
8d40: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
8d50: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
8d60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
8d70: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
8d80: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
8d90: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
8da0: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
8db0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
8dc0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
8dd0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
8de0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
8df0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
8e00: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
8e10: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
8e20: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
8e30: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
8e40: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
8e50: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
8e60: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
8e70: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
8e80: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
8e90: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
8ea0: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
8eb0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
8ec0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
8ed0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
8ee0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
8ef0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
8f00: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
8f10: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
8f20: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
8f30: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
8f40: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
8f50: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
8f60: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
8f70: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
8f80: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
8f90: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
8fa0: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
8fb0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
8fc0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
8fd0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
8fe0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
8ff0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
9000: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
9010: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
9020: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
9030: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
9040: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
9050: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
9060: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
9070: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
9080: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
9090: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
90a0: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
90b0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
90c0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
90d0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
90e0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
90f0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
9100: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
9110: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
9120: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
9130: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
9140: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
9150: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
9160: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
9170: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
9180: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
9190: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
91a0: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
91b0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
91c0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
91d0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
91e0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
91f0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
9200: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
9210: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
9220: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
9230: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
9240: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
9250: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
9260: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
9270: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
9280: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
9290: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
92a0: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
92b0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
92c0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
92d0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
92e0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
92f0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
9300: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
9310: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
9320: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
9330: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
9340: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
9350: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
9360: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
9370: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
9380: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
9390: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
93a0: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
93b0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
93c0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
93d0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
93e0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
93f0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
9400: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
9410: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
9420: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
9430: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
9440: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
9450: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
9460: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
9470: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
9480: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
9490: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
94a0: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
94b0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
94c0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
94d0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
94e0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
94f0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
9500: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
9510: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
9520: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
9530: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
9540: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
9550: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
9560: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
9570: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
9580: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
9590: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
95a0: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
95b0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
95c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
95d0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
95e0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
95f0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
9600: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
9610: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
9620: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
9630: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
9640: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9650: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
9660: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
9670: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
9680: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9690: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
96a0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
96b0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
96c0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
96d0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
96e0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
96f0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
9700: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
9710: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
9720: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
9730: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
9740: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
9750: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
9760: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
9770: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
9780: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
9790: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
97a0: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
97b0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
97c0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
97d0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
97e0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
97f0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
9800: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
9810: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
9820: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
9830: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
9840: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
9850: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
9860: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
9870: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
9880: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
9890: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
98a0: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
98b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
98c0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
98d0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
98e0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
98f0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
9900: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
9910: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
9920: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
9930: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
9940: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
9950: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
9960: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
9970: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
9980: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
9990: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
99a0: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
99b0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
99c0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
99d0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
99e0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
99f0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
9a00: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
9a10: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
9a20: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
9a30: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
9a40: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
9a50: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
9a60: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
9a70: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
9a80: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
9a90: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
9aa0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
9ab0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
9ac0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
9ad0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
9ae0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
9af0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
9b00: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
9b10: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
9b20: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
9b30: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
9b40: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
9b50: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
9b60: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
9b70: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
9b80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
9b90: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
9ba0: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
9bb0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
9bc0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
9bd0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
9be0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
9bf0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
9c00: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
9c10: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
9c20: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
9c30: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
9c40: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
9c50: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
9c60: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
9c70: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
9c80: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
9c90: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
9ca0: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
9cb0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
9cc0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
9cd0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9ce0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
9cf0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
9d00: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
9d10: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
9d20: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
9d30: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
9d40: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
9d50: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
9d60: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
9d70: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
9d80: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
9d90: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
9da0: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
9db0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
9dc0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
9dd0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
9de0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
9df0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
9e00: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
9e10: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
9e20: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
9e30: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
9e40: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
9e50: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
9e60: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
9e70: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
9e80: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
9e90: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
9ea0: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
9eb0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
9ec0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
9ed0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
9ee0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
9ef0: 65 2e 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f  e..** A [file co
9f00: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20  ntrol opcodes | 
9f10: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
9f20: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
9f30: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
9f40: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
9f50: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
9f60: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
9f70: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
9f80: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
9f90: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
9fa0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
9fb0: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
9fc0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
9fd0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
9fe0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
9ff0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
a000: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
a010: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
a020: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
a030: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
a040: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
a050: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
a060: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
a070: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
a080: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
a090: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
a0a0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
a0b0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
a0c0: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
a0d0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
a0e0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
a0f0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
a100: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
a110: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
a120: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
a130: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
a140: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
a150: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
a160: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
a170: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
a180: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
a190: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
a1a0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
a1b0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
a1c0: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
a1d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
a1e0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
a1f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
a200: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
a210: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
a220: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
a230: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
a240: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
a250: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
a260: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
a270: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
a280: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
a290: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
a2a0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
a2b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
a2c0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
a2d0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
a2e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
a2f0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
a300: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
a310: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
a320: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
a330: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
a340: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
a350: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
a360: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
a370: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
a380: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
a390: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
a3a0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
a3b0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
a3c0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
a3d0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
a3e0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
a3f0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
a400: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
a410: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
a420: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
a430: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
a440: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
a450: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
a460: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
a470: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
a480: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
a490: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
a4a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
a4b0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
a4c0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
a4d0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
a4e0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
a4f0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
a500: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
a510: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
a520: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
a530: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
a540: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
a550: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
a560: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
a570: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
a580: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
a590: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
a5a0: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
a5b0: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
a5c0: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
a5d0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
a5e0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
a5f0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
a600: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
a610: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
a620: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
a630: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
a640: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
a650: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
a660: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
a670: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
a680: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
a690: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
a6a0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
a6b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
a6c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a6d0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
a6e0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
a6f0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
a700: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
a710: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
a720: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
a730: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
a740: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
a750: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
a760: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
a770: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
a780: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
a790: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
a7a0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
a7b0: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
a7c0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
a7d0: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
a7e0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
a7f0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
a800: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
a810: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
a820: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
a830: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
a840: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
a850: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
a860: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
a870: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
a880: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
a890: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
a8a0: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
a8b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
a8c0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
a8d0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
a8e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
a8f0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
a900: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
a910: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
a920: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
a930: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
a940: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
a950: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
a960: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
a970: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
a980: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
a990: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
a9a0: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
a9b0: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
a9c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
a9d0: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
a9e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a9f0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
aa00: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
aa10: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
aa20: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
aa30: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
aa40: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
aa50: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
aa60: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
aa70: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
aa80: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
aa90: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
aaa0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
aab0: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
aac0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
aad0: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
aae0: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
aaf0: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
ab00: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
ab10: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
ab20: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
ab30: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
ab40: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
ab50: 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  odes.** KEYWORDS
ab60: 3a 20 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  : {file control 
ab70: 6f 70 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63  opcodes} {file c
ab80: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a  ontrol opcode}.*
ab90: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
aba0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
abb0: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
abc0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
abd0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
abe0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
abf0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
ac00: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
ac10: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
ac20: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
ac30: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
ac40: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  [[SQLITE_FCNTL_L
ac50: 4f 43 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68  OCKSTATE]].** Th
ac60: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ac70: 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64  LOCKSTATE] opcod
ac80: 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65  e is used for de
ac90: 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a  bugging.  This.*
aca0: 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20  * opcode causes 
acb0: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
acc0: 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65   method to write
acd0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
ace0: 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63  te of.** the loc
acf0: 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  k (one of [SQLIT
ad00: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53  E_LOCK_NONE], [S
ad10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45  QLITE_LOCK_SHARE
ad20: 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c  D],.** [SQLITE_L
ad30: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b  OCK_RESERVED], [
ad40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
ad50: 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ING], or [SQLITE
ad60: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
ad70: 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74  ).** into an int
ad80: 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41  eger that the pA
ad90: 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  rg argument poin
ada0: 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61  ts to. This capa
adb0: 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65  bility.** is use
adc0: 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
add0: 20 61 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61   and is only ava
ade0: 69 6c 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20  ilable when the 
adf0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63  SQLITE_TEST.** c
ae00: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
ae10: 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
ae20: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
ae30: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
ae40: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
ae50: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
ae60: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
ae70: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
ae80: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
ae90: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
aea0: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
aeb0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
aec0: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
aed0: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
aee0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
aef0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
af00: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
af10: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
af20: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
af30: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
af40: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
af50: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
af60: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
af70: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
af80: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
af90: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
afa0: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
afb0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
afc0: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
afd0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
afe0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
aff0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b000: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
b010: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
b020: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
b030: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
b040: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
b050: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b060: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
b070: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
b080: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
b090: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
b0a0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
b0b0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
b0c0: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
b0d0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
b0e0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
b0f0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
b100: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
b110: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
b120: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
b130: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
b140: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
b150: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
b160: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
b170: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
b180: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
b190: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
b1a0: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
b1b0: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
b1c0: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
b1d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
b1e0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
b1f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b200: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
b210: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
b220: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
b230: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
b240: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
b250: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
b260: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
b270: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
b280: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
b290: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
b2a0: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
b2b0: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
b2c0: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
b2d0: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
b2e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b2f0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
b300: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
b310: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
b320: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
b330: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
b340: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
b350: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
b360: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
b370: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
b380: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
b390: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
b3a0: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
b3b0: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
b3c0: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
b3d0: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
b3e0: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
b3f0: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
b400: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
b410: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
b420: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
b430: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
b440: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
b450: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
b460: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
b470: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
b480: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
b490: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
b4a0: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
b4b0: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
b4c0: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
b4d0: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
b4e0: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
b4f0: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
b500: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
b510: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
b520: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
b530: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
b540: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
b550: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
b560: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
b570: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
b580: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
b590: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
b5a0: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
b5b0: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
b5c0: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
b5d0: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
b5e0: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
b5f0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
b600: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
b610: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
b620: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
b630: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
b640: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
b650: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
b660: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
b670: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
b680: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
b690: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
b6a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
b6b0: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
b6c0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
b6d0: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
b6e0: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
b6f0: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
b700: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
b710: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
b720: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
b730: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
b740: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
b750: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
b760: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
b770: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
b780: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
b790: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
b7a0: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
b7b0: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
b7c0: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
b7d0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
b7e0: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
b7f0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
b800: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
b810: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
b820: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
b830: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
b840: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
b850: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
b860: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
b870: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b880: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
b890: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
b8a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
b8b0: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
b8c0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
b8d0: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
b8e0: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
b8f0: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
b900: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
b910: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
b920: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
b930: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
b940: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
b950: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
b960: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
b970: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
b980: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
b990: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
b9a0: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
b9b0: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
b9c0: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
b9d0: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
b9e0: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
b9f0: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
ba00: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
ba10: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
ba20: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
ba30: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
ba40: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
ba50: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
ba60: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
ba70: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
ba80: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
ba90: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
baa0: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
bab0: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
bac0: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
bad0: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
bae0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
baf0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
bb00: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
bb10: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bb20: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
bb30: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
bb40: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
bb50: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
bb60: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
bb70: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
bb80: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
bb90: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
bba0: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
bbb0: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
bbc0: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
bbd0: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
bbe0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
bbf0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
bc00: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
bc10: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
bc20: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
bc30: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
bc40: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
bc50: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
bc60: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
bc70: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
bc80: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
bc90: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
bca0: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
bcb0: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
bcc0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
bcd0: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
bce0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
bcf0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
bd00: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
bd10: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
bd20: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
bd30: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
bd40: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
bd50: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
bd60: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
bd70: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
bd80: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
bd90: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
bda0: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
bdb0: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
bdc0: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
bdd0: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
bde0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
bdf0: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
be00: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
be10: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
be20: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
be30: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
be40: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
be50: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
be60: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
be70: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
be80: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
be90: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
bea0: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
beb0: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
bec0: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
bed0: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
bee0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
bef0: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
bf00: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
bf10: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
bf20: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
bf30: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
bf40: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
bf50: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
bf60: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
bf70: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
bf80: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
bf90: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
bfa0: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
bfb0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
bfc0: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
bfd0: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
bfe0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
bff0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
c000: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
c010: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
c020: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
c030: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
c040: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
c050: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
c060: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
c070: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
c080: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
c090: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
c0a0: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
c0b0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
c0c0: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
c0d0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
c0e0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
c0f0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
c100: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
c110: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
c120: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
c130: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
c140: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
c150: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
c160: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
c170: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
c180: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
c190: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
c1a0: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
c1b0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
c1c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
c1d0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
c1e0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
c1f0: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
c200: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
c210: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
c220: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
c230: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
c240: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
c250: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
c260: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
c270: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
c280: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
c290: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
c2a0: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
c2b0: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
c2c0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
c2d0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
c2e0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
c2f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
c300: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
c310: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
c320: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
c330: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
c340: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
c350: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
c360: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
c370: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
c380: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
c390: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
c3a0: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
c3b0: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
c3c0: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
c3d0: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
c3e0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
c3f0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
c400: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
c410: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
c420: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
c430: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
c440: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
c450: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
c460: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
c470: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
c480: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
c490: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
c4a0: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
c4b0: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
c4c0: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
c4d0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
c4e0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
c4f0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
c500: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
c510: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
c520: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
c530: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
c540: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
c550: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
c560: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
c570: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
c580: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
c590: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
c5a0: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
c5b0: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
c5c0: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
c5d0: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
c5e0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
c5f0: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
c600: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
c610: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
c620: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
c630: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
c640: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
c650: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
c660: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
c670: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
c680: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
c690: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
c6a0: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
c6b0: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
c6c0: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
c6d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
c6e0: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
c6f0: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
c700: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
c710: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
c720: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
c730: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
c740: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
c750: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
c760: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
c770: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
c780: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
c790: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
c7a0: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
c7b0: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
c7c0: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
c7d0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
c7e0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
c7f0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
c800: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
c810: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
c820: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
c830: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
c840: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
c850: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
c860: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
c870: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
c880: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
c890: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
c8a0: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
c8b0: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
c8c0: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
c8d0: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
c8e0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
c8f0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
c900: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
c910: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
c920: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
c930: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
c940: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
c950: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
c960: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
c970: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
c980: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
c990: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
c9a0: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
c9b0: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
c9c0: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
c9d0: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
c9e0: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
c9f0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
ca00: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
ca10: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
ca20: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
ca30: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
ca40: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
ca50: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
ca60: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
ca70: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
ca80: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
ca90: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
caa0: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
cab0: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
cac0: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
cad0: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
cae0: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
caf0: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
cb00: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
cb10: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
cb20: 20 69 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e   if result strin
cb30: 67 20 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68  g is NULL, or th
cb40: 61 74 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  at returns a cop
cb50: 79 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  y.** of the resu
cb60: 6c 74 20 73 74 72 69 6e 67 20 69 66 20 74 68 65  lt string if the
cb70: 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e   string is non-N
cb80: 55 4c 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ULL..** ^If the 
cb90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
cba0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
cbb0: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
cbc0: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
cbd0: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
cbe0: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
cbf0: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
cc00: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
cc10: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
cc20: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
cc30: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
cc40: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
cc50: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
cc60: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
cc70: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
cc80: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
cc90: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
cca0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
ccb0: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
ccc0: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
ccd0: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
cce0: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
ccf0: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
cd00: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
cd10: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
cd20: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
cd30: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
cd40: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
cd50: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
cd60: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
cd70: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
cd80: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
cd90: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
cda0: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
cdb0: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
cdc0: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
cdd0: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
cde0: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
cdf0: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
ce00: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ce10: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
ce20: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
ce30: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
ce40: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
ce50: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
ce60: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
ce70: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
ce80: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
ce90: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
cea0: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
ceb0: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
cec0: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
ced0: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
cee0: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
cef0: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
cf00: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
cf10: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
cf20: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
cf30: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
cf40: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
cf50: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
cf60: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
cf70: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
cf80: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
cf90: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
cfa0: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
cfb0: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
cfc0: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
cfd0: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
cfe0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
cff0: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
d000: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
d010: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
d020: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
d030: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
d040: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
d050: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
d060: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
d070: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
d080: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
d090: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
d0a0: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
d0b0: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
d0c0: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
d0d0: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
d0e0: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
d0f0: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
d100: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
d110: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
d120: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
d130: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
d140: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
d150: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
d160: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
d170: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
d180: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
d190: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
d1a0: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
d1b0: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
d1c0: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
d1d0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
d1e0: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
d1f0: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
d200: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
d210: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
d220: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
d230: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
d240: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
d250: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
d260: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
d270: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
d280: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
d290: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
d2a0: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
d2b0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
d2c0: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
d2d0: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
d2e0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
d2f0: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
d300: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
d310: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
d320: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
d330: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
d340: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
d350: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
d360: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
d370: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
d380: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
d390: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
d3a0: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
d3b0: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
d3c0: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
d3d0: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
d3e0: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
d3f0: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
d400: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
d410: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
d420: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
d430: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
d440: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
d450: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
d460: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
d470: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
d480: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
d490: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
d4a0: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
d4b0: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
d4c0: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
d4d0: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
d4e0: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
d4f0: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
d500: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
d510: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
d520: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
d530: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
d540: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
d550: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
d560: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
d570: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
d580: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
d590: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
d5a0: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
d5b0: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
d5c0: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
d5d0: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
d5e0: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
d5f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
d600: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
d610: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
d620: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
d630: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
d640: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
d650: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
d660: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
d670: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
d680: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
d690: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
d6a0: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
d6b0: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
d6c0: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
d6d0: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
d6e0: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
d6f0: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
d700: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d710: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
d720: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
d730: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d740: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
d750: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
d760: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
d770: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
d780: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
d790: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
d7a0: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
d7b0: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
d7c0: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
d7d0: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
d7e0: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
d7f0: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
d800: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
d810: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
d820: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
d830: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
d840: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
d850: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d860: 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c  ITE_FCNTL_WAL_BL
d870: 4f 43 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  OCK]].** The [SQ
d880: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42  LITE_FCNTL_WAL_B
d890: 4c 4f 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61  LOCK] is a signa
d8a0: 6c 20 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79  l to the VFS lay
d8b0: 65 72 20 74 68 61 74 20 69 74 20 6d 69 67 68 74  er that it might
d8c0: 0a 2a 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65  .** be advantage
d8d0: 6f 75 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20  ous to block on 
d8e0: 74 68 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63  the next WAL loc
d8f0: 6b 20 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73  k if the lock is
d900: 20 6e 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79   not immediately
d910: 0a 2a 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20  .** available.  
d920: 54 68 65 20 57 41 4c 20 73 75 62 73 79 73 74 65  The WAL subsyste
d930: 6d 20 69 73 73 75 65 73 20 74 68 69 73 20 73 69  m issues this si
d940: 67 6e 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65  gnal during rare
d950: 0a 2a 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65  .** circumstance
d960: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  s in order to fi
d970: 78 20 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68  x a problem with
d980: 20 70 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73   priority invers
d990: 69 6f 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ion..** Applicat
d9a0: 69 6f 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e  ions should <em>
d9b0: 6e 6f 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69  not</em> use thi
d9c0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a  s file-control..
d9d0: 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23  **.** </ul>.*/.#
d9e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
d9f0: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20  NTL_LOCKSTATE   
da00: 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
da10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
da20: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
da30: 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64 65  FILE       2.#de
da40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
da50: 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  L_SET_LOCKPROXYF
da60: 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65 66  ILE       3.#def
da70: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
da80: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
da90: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
daa0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
dab0: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
dac0: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
dad0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
dae0: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
daf0: 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
db00: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49   SQLITE_FCNTL_FI
db10: 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20  LE_POINTER      
db20: 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
db30: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
db40: 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20  C_OMITTED       
db50: 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
db60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
db70: 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20  2_AV_RETRY      
db80: 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
db90: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
dba0: 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  ST_WAL          
dbb0: 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
dbc0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
dbd0: 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ITE             
dbe0: 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   11.#define SQLI
dbf0: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
dc00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
dc10: 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  12.#define SQLIT
dc20: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
dc30: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31  E_OVERWRITE    1
dc40: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
dc50: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20  _FCNTL_PRAGMA   
dc60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34                14
dc70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dc80: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
dc90: 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a  R            15.
dca0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dcb0: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
dcc0: 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 23  E           16.#
dcd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dce0: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  NTL_MMAP_SIZE   
dcf0: 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23 64             18.#d
dd00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
dd10: 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20 20  TL_TRACE        
dd20: 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64 65            19.#de
dd30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
dd40: 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20 20  L_HAS_MOVED     
dd50: 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65 66           20.#def
dd60: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
dd70: 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20 20  _SYNC           
dd80: 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66 69          21.#defi
dd90: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
dda0: 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 20  COMMIT_PHASETWO 
ddb0: 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69 6e         22.#defin
ddc0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
ddd0: 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 20  IN32_SET_HANDLE 
dde0: 20 20 20 20 20 20 32 33 0a 23 64 65 66 69 6e 65        23.#define
ddf0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 41   SQLITE_FCNTL_WA
de00: 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  L_BLOCK         
de10: 20 20 20 20 20 32 34 0a 0a 2f 2a 20 64 65 70 72       24../* depr
de20: 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f 0a  ecated names */.
de30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
de40: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
de50: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
de60: 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_GET_LOCKPROXY
de70: 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51 4c  FILE.#define SQL
de80: 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_SET_LOCKPROX
de90: 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49 54  YFILE      SQLIT
dea0: 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b  E_FCNTL_SET_LOCK
deb0: 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69 6e  PROXYFILE.#defin
dec0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
ded0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
dee0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41 53  SQLITE_FCNTL_LAS
def0: 54 5f 45 52 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20  T_ERRNO.../*.** 
df00: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
df10: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
df20: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
df30: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
df40: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
df50: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
df60: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
df70: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
df80: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
df90: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
dfa0: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
dfb0: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
dfc0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
dfd0: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
dfe0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
dff0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
e000: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
e010: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
e020: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
e030: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
e040: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
e050: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
e060: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
e070: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
e080: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e090: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
e0a0: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
e0b0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
e0c0: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
e0d0: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
e0e0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
e0f0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
e100: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
e110: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
e120: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
e130: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
e140: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
e150: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
e160: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
e170: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
e180: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
e190: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
e1a0: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
e1b0: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
e1c0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
e1d0: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
e1e0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
e1f0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
e200: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
e210: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
e220: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
e230: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
e240: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
e250: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
e260: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
e270: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
e280: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
e290: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
e2a0: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
e2b0: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
e2c0: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
e2d0: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
e2e0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
e2f0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
e300: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
e310: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
e320: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
e330: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
e340: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
e350: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
e360: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
e370: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
e380: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
e390: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
e3a0: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
e3b0: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
e3c0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
e3d0: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
e3e0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
e3f0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
e400: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
e410: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
e420: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
e430: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
e440: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
e450: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
e460: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
e470: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
e480: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
e490: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
e4a0: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
e4b0: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
e4c0: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
e4d0: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
e4e0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
e4f0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
e500: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
e510: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
e520: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
e530: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
e540: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
e550: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
e560: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
e570: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
e580: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
e590: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
e5a0: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
e5b0: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
e5c0: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
e5d0: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
e5e0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
e5f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
e600: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
e610: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
e620: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
e630: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
e640: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
e650: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
e660: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
e670: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
e680: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
e690: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
e6a0: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
e6b0: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
e6c0: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
e6d0: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
e6e0: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
e6f0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
e700: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
e710: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
e720: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
e730: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
e740: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
e750: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
e760: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
e770: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
e780: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
e790: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
e7a0: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
e7b0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
e7c0: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
e7d0: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
e7e0: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
e7f0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
e800: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
e810: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
e820: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
e830: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
e840: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
e850: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
e860: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
e870: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
e880: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
e890: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
e8a0: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
e8b0: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
e8c0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
e8d0: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
e8e0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
e8f0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
e900: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
e910: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
e920: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
e930: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
e940: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
e950: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
e960: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
e970: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
e980: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
e990: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
e9a0: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
e9b0: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
e9c0: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
e9d0: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
e9e0: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
e9f0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
ea00: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
ea10: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
ea20: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
ea30: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
ea40: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
ea50: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
ea60: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
ea70: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
ea80: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
ea90: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
eaa0: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
eab0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
eac0: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
ead0: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
eae0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
eaf0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
eb00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
eb10: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
eb20: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
eb30: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
eb40: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
eb50: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
eb60: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
eb70: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
eb80: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
eb90: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
eba0: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
ebb0: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
ebc0: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
ebd0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
ebe0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
ebf0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
ec00: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
ec10: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
ec20: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
ec30: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
ec40: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ec50: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
ec60: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
ec70: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
ec80: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ec90: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
eca0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ecb0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
ecc0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ecd0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
ece0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
ecf0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
ed00: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
ed10: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
ed20: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
ed30: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ed40: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
ed50: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
ed60: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
ed70: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
ed80: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
ed90: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
eda0: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
edb0: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
edc0: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
edd0: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
ede0: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
edf0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
ee00: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
ee10: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
ee20: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
ee30: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
ee40: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
ee50: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
ee60: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
ee70: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
ee80: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
ee90: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
eea0: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
eeb0: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
eec0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
eed0: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
eee0: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
eef0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
ef00: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
ef10: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
ef20: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
ef30: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
ef40: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
ef50: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
ef60: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
ef70: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
ef80: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
ef90: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
efa0: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
efb0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
efc0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
efd0: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
efe0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
eff0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
f000: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
f010: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
f020: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
f030: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
f040: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
f050: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
f060: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
f070: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
f080: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
f090: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
f0a0: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
f0b0: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
f0c0: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
f0d0: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
f0e0: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
f0f0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
f100: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
f110: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
f120: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
f130: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
f140: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
f150: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
f160: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
f170: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
f180: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
f190: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
f1a0: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
f1b0: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
f1c0: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
f1d0: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
f1e0: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
f1f0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
f200: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
f210: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
f220: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
f230: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
f240: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
f250: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
f260: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
f270: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
f280: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
f290: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
f2a0: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
f2b0: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
f2c0: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
f2d0: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
f2e0: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
f2f0: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
f300: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
f310: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
f320: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
f330: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
f340: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
f350: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
f360: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
f370: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
f380: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
f390: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
f3a0: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
f3b0: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
f3c0: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
f3d0: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
f3e0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
f3f0: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
f400: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
f410: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f420: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
f430: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
f440: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
f450: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
f460: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
f470: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
f480: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
f490: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
f4a0: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
f4b0: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
f4c0: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
f4d0: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
f4e0: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
f4f0: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
f500: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
f510: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
f520: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
f530: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
f540: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
f550: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
f560: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
f570: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
f580: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
f590: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
f5a0: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
f5b0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
f5c0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
f5d0: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
f5e0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
f5f0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
f600: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
f610: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
f620: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
f630: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
f640: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
f650: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
f660: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
f670: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
f680: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
f690: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
f6a0: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
f6b0: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
f6c0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
f6d0: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
f6e0: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
f6f0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
f700: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
f710: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
f720: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
f730: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
f740: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
f750: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
f760: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
f770: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
f780: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
f790: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
f7a0: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
f7b0: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
f7c0: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
f7d0: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
f7e0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
f7f0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
f800: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
f810: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
f820: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
f830: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
f840: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
f850: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
f860: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
f870: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
f880: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
f890: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
f8a0: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
f8b0: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
f8c0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
f8d0: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
f8e0: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
f8f0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
f900: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
f910: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
f920: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
f930: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
f940: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
f950: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
f960: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
f970: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
f980: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
f990: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
f9a0: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
f9b0: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
f9c0: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
f9d0: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
f9e0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
f9f0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
fa00: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
fa10: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
fa20: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
fa30: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
fa40: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
fa50: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
fa60: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
fa70: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
fa80: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
fa90: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
faa0: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
fab0: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
fac0: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
fad0: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
fae0: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
faf0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
fb00: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
fb10: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
fb20: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
fb30: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
fb40: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
fb50: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
fb60: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
fb70: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
fb80: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
fb90: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
fba0: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
fbb0: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
fbc0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
fbd0: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
fbe0: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
fbf0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
fc00: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
fc10: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
fc20: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
fc30: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
fc40: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
fc50: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
fc60: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
fc70: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
fc80: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
fc90: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
fca0: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
fcb0: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
fcc0: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
fcd0: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
fce0: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
fcf0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
fd00: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
fd10: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
fd20: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
fd30: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
fd40: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
fd50: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
fd60: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
fd70: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
fd80: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
fd90: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
fda0: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
fdb0: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
fdc0: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
fdd0: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
fde0: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
fdf0: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
fe00: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
fe10: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
fe20: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
fe30: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
fe40: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
fe50: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
fe60: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
fe70: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
fe80: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
fe90: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
fea0: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
feb0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
fec0: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
fed0: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
fee0: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
fef0: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
ff00: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
ff10: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
ff20: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
ff30: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
ff40: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
ff50: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
ff60: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
ff70: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
ff80: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
ff90: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
ffa0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
ffb0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
ffc0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
ffd0: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
ffe0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
fff0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
10000 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
10010 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
10020 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
10030 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
10040 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
10050 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
10060 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
10070 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
10080 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
10090 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
100a0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
100b0 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
100c0 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
100d0 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
100e0 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
100f0 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
10100 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
10110 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
10120 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10130 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10140 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
10150 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
10160 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
10170 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
10180 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
10190 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
101a0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
101b0 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
101c0 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
101d0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
101e0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
101f0 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
10200 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
10210 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
10220 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
10230 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
10240 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
10250 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
10260 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
10270 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
10280 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
10290 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
102a0 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
102b0 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
102c0 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
102d0 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
102e0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
102f0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
10300 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
10310 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
10320 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
10330 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
10340 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
10350 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
10360 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
10370 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
10380 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
10390 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
103a0 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
103b0 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
103c0 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
103d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
103e0 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
103f0 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
10400 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
10410 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
10420 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
10430 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
10440 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
10450 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
10460 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
10470 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
10480 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
10490 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
104a0 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
104b0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
104c0 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
104d0 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
104e0 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
104f0 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
10500 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
10510 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
10520 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
10530 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
10540 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
10550 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
10560 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
10570 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
10580 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
10590 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
105a0 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
105b0 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
105c0 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
105d0 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
105e0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
105f0 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
10600 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
10610 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
10620 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
10630 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
10640 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
10650 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
10660 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
10670 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
10680 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
10690 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
106a0 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
106b0 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
106c0 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
106d0 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
106e0 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
106f0 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
10700 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
10710 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
10720 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
10730 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
10740 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
10750 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
10760 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
10770 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
10780 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
10790 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
107a0 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
107b0 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
107c0 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
107d0 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
107e0 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
107f0 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
10800 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
10810 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
10820 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
10830 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
10840 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
10850 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
10860 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
10870 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
10880 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
10890 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
108a0 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
108b0 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
108c0 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
108d0 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
108e0 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
108f0 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
10900 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
10910 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
10920 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
10930 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
10940 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
10950 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
10960 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
10970 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
10980 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
10990 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
109a0 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
109b0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
109c0 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
109d0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
109e0 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
109f0 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
10a00 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
10a10 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
10a20 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
10a30 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
10a40 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
10a50 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
10a60 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
10a70 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
10a80 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
10a90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
10aa0 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
10ab0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
10ac0 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
10ad0 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
10ae0 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
10af0 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
10b00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
10b10 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
10b20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
10b30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
10b40 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
10b50 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
10b60 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
10b70 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
10b80 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
10b90 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
10ba0 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
10bb0 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
10bc0 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
10bd0 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
10be0 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
10bf0 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
10c00 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
10c10 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
10c20 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
10c30 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
10c40 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
10c50 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
10c60 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
10c70 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
10c80 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
10c90 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
10ca0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
10cb0 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
10cc0 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
10cd0 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
10ce0 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
10cf0 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
10d00 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
10d10 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
10d20 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
10d30 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
10d40 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
10d50 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
10d60 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f 72 72 65  ven on the corre
10d70 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
10d80 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
10d90 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
10da0 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
10db0 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
10dc0 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
10dd0 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
10de0 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
10df0 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
10e00 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
10e10 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
10e20 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
10e30 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
10e40 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
10e50 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
10e60 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
10e70 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
10e80 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
10e90 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
10ea0 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
10eb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
10ec0 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
10ed0 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
10ee0 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
10ef0 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
10f00 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
10f10 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
10f20 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
10f30 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
10f40 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
10f50 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
10f60 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
10f70 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
10f80 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
10f90 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
10fa0 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
10fb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10fc0 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
10fd0 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
10fe0 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
10ff0 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
11000 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
11010 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11020 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
11030 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
11040 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
11050 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
11060 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
11070 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
11080 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
11090 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
110a0 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
110b0 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
110c0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
110d0 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
110e0 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
110f0 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
11100 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
11110 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
11120 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
11130 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
11140 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
11150 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
11160 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
11170 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
11180 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
11190 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
111a0 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
111b0 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
111c0 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
111d0 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
111e0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
111f0 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
11200 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
11210 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
11220 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
11230 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
11240 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
11250 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
11260 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
11270 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
11280 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
11290 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
112a0 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
112b0 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
112c0 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
112d0 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
112e0 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
112f0 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
11300 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
11310 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11320 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
11330 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
11340 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
11350 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
11360 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
11370 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
11380 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
11390 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
113a0 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
113b0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
113c0 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
113d0 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
113e0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
113f0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
11400 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
11410 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
11420 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
11430 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11440 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
11450 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
11460 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
11470 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
11480 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
11490 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
114a0 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
114b0 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
114c0 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
114d0 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
114e0 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
114f0 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
11500 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
11510 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
11520 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
11530 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
11540 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
11550 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
11560 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
11570 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
11580 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
11590 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
115a0 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
115b0 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
115c0 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
115d0 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
115e0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
115f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
11600 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
11610 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
11620 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
11630 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
11640 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
11650 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
11660 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
11670 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
11680 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
11690 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
116a0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
116b0 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
116c0 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
116d0 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
116e0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
116f0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
11700 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
11710 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11720 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
11730 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
11740 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
11750 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
11760 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
11770 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
11780 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
11790 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
117a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
117b0 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
117c0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
117d0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
117e0 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
117f0 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
11800 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
11810 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
11820 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
11830 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
11840 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
11850 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
11860 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
11870 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
11880 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
11890 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
118a0 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
118b0 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
118c0 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
118d0 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
118e0 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
118f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
11900 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
11910 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
11920 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
11930 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
11940 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
11950 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
11960 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
11970 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
11980 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
11990 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
119a0 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
119b0 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
119c0 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
119d0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
119e0 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
119f0 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
11a00 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
11a10 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
11a20 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
11a30 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
11a40 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
11a50 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
11a60 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
11a70 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
11a80 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11a90 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
11aa0 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
11ab0 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
11ac0 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
11ad0 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
11ae0 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
11af0 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
11b00 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
11b10 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
11b20 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
11b30 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
11b40 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
11b50 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
11b60 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
11b70 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
11b80 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
11b90 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
11ba0 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
11bb0 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
11bc0 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
11bd0 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
11be0 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
11bf0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
11c00 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
11c10 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
11c20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
11c30 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
11c40 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
11c50 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
11c60 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
11c70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
11c80 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
11c90 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
11ca0 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
11cb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
11cc0 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
11cd0 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
11ce0 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
11cf0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
11d00 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
11d10 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
11d20 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
11d30 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
11d40 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
11d50 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
11d60 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
11d70 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
11d80 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
11d90 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
11da0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11db0 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
11dc0 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
11dd0 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
11de0 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
11df0 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
11e00 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
11e10 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
11e20 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
11e30 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
11e40 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
11e50 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
11e60 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
11e70 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
11e80 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
11e90 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
11ea0 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
11eb0 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
11ec0 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
11ed0 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
11ee0 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
11ef0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
11f00 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
11f10 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
11f20 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
11f30 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
11f40 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
11f50 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
11f60 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
11f70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
11f80 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11f90 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
11fa0 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
11fb0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
11fc0 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
11fd0 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
11fe0 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
11ff0 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49  failure..*/.SQLI
12000 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
12010 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
12020 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69  3_initialize(voi
12030 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  d);.SQLITE_API i
12040 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
12050 4c 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  L sqlite3_shutdo
12060 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  wn(void);.SQLITE
12070 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
12080 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
12090 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53  os_init(void);.S
120a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
120b0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
120c0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
120d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
120e0 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
120f0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
12100 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
12110 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
12120 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
12130 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
12140 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
12150 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
12160 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
12170 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
12180 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
12190 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
121a0 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
121b0 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
121c0 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
121d0 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
121e0 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
121f0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
12200 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
12210 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
12220 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
12230 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
12240 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
12250 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
12260 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
12270 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
12280 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
12290 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
122a0 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
122b0 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
122c0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
122d0 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
122e0 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
122f0 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
12300 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
12310 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
12320 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
12330 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
12340 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
12350 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
12360 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
12370 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
12380 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
12390 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
123a0 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
123b0 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
123c0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
123d0 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
123e0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
123f0 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
12400 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
12410 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
12420 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
12430 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
12440 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
12450 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
12460 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
12470 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
12480 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
12490 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
124a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
124b0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
124c0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
124d0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
124e0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
124f0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
12500 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
12510 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
12520 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
12530 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
12540 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
12550 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
12560 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
12570 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
12580 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
12590 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
125a0 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
125b0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
125c0 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
125d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
125e0 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
125f0 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
12600 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
12610 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
12620 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
12630 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
12640 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
12650 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
12660 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
12670 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
12680 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
12690 20 69 6e 74 20 53 51 4c 49 54 45 5f 43 44 45 43   int SQLITE_CDEC
126a0 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  L sqlite3_config
126b0 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
126c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
126d0 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
126e0 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d  connections.** M
126f0 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
12700 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
12710 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
12720 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
12730 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
12740 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
12750 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
12760 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
12770 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
12780 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
12790 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
127a0 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
127b0 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
127c0 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
127d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
127e0 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
127f0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
12800 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
12810 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
12820 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
12830 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
12840 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
12850 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
12860 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
12870 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
12880 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
12890 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
128a0 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
128b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
128c0 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
128d0 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
128e0 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
128f0 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
12900 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
12910 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
12920 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
12930 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
12940 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
12950 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
12960 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
12970 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
12980 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  essful..*/.SQLIT
12990 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
129a0 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 64  _CDECL sqlite3_d
129b0 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33  b_config(sqlite3
129c0 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b  *, int op, ...);
129d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
129e0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
129f0 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a  ion Routines.**.
12a00 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ** An instance o
12a10 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65  f this object de
12a20 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
12a30 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69  ace between SQLi
12a40 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65  te.** and low-le
12a50 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
12a60 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a  ation routines..
12a70 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  **.** This objec
12a80 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c  t is used in onl
12a90 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74  y one place in t
12aa0 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  he SQLite interf
12ab0 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65  ace..** A pointe
12ac0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
12ad0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
12ae0 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
12af0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
12b00 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68  onfig()] when th
12b10 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
12b20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51  option is.** [SQ
12b30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
12b40 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  OC] or [SQLITE_C
12b50 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
12b60 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69  .  .** By creati
12b70 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  ng an instance o
12b80 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a  f this object.**
12b90 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20   and passing it 
12ba0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
12bb0 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
12bc0 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64  IG_MALLOC]).** d
12bd0 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  uring configurat
12be0 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ion, an applicat
12bf0 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20  ion can specify 
12c00 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
12c10 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
12c20 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f  ion subsystem fo
12c30 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20  r SQLite to use 
12c40 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a  for all of its.*
12c50 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  * dynamic memory
12c60 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   needs..**.** No
12c70 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  te that SQLite c
12c80 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61  omes with severa
12c90 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  l [built-in memo
12ca0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a  ry allocators].*
12cb0 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65  * that are perfe
12cc0 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f  ctly adequate fo
12cd0 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69  r the overwhelmi
12ce0 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61  ng majority of a
12cf0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61  pplications.** a
12d00 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a  nd that this obj
12d10 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66  ect is only usef
12d20 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e  ul to a tiny min
12d30 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61  ority of applica
12d40 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70  tions.** with sp
12d50 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79  ecialized memory
12d60 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
12d70 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20  irements.  This 
12d80 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73  object is.** als
12d90 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  o used during te
12da0 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20  sting of SQLite 
12db0 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63  in order to spec
12dc0 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  ify an alternati
12dd0 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c  ve.** memory all
12de0 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75  ocator that simu
12df0 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74  lates memory out
12e00 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69  -of-memory condi
12e10 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65  tions in.** orde
12e20 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  r to verify that
12e30 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73   SQLite recovers
12e40 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d   gracefully from
12e50 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69   such.** conditi
12e60 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ons..**.** The x
12e70 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63  Malloc, xRealloc
12e80 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68  , and xFree meth
12e90 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69  ods must work li
12ea0 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63  ke the.** malloc
12eb0 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e  (), realloc() an
12ec0 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f  d free() functio
12ed0 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ns from the stan
12ee0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
12ef0 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61  ** ^SQLite guara
12f00 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73  ntees that the s
12f10 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
12f20 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73  o.** xRealloc is
12f30 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20   always a value 
12f40 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72  returned by a pr
12f50 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75  ior call to xRou
12f60 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a  ndup..**.** xSiz
12f70 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20  e should return 
12f80 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
12f90 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61  ze of a memory a
12fa0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65  llocation.** pre
12fb0 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64  viously obtained
12fc0 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72   from xMalloc or
12fd0 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20   xRealloc.  The 
12fe0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a  allocated size.*
12ff0 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c  * is always at l
13000 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20 74  east as big as t
13010 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  he requested siz
13020 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  e but may be lar
13030 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ger..**.** The x
13040 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72  Roundup method r
13050 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c  eturns what woul
13060 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74  d be the allocat
13070 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20  ed size of.** a 
13080 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13090 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69 63  n given a partic
130a0 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20 73  ular requested s
130b0 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72  ize.  Most memor
130c0 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20  y.** allocators 
130d0 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20  round up memory 
130e0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c  allocations at l
130f0 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74  east to the next
13100 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20   multiple.** of 
13110 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74  8.  Some allocat
13120 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20  ors round up to 
13130 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c  a larger multipl
13140 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20  e or to a power 
13150 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d  of 2..** Every m
13160 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13170 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20   request coming 
13180 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69  in through [sqli
13190 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  te3_malloc()].**
131a0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
131b0 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61  lloc()] first ca
131c0 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49  lls xRoundup.  I
131d0 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72  f xRoundup retur
131e0 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63  ns 0, .** that c
131f0 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65 73  auses the corres
13200 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61  ponding memory a
13210 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69  llocation to fai
13220 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e  l..**.** The xIn
13230 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61  it method initia
13240 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  lizes the memory
13250 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72   allocator.  For
13260 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20   example,.** it 
13270 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61  might allocate a
13280 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78  ny require mutex
13290 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65  es or initialize
132a0 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a   internal data.*
132b0 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54  * structures.  T
132c0 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  he xShutdown met
132d0 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  hod is invoked (
132e0 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a  indirectly) by.*
132f0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  * [sqlite3_shutd
13300 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c  own()] and shoul
13310 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79  d deallocate any
13320 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69   resources acqui
13330 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e  red.** by xInit.
13340 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70    The pAppData p
13350 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61  ointer is used a
13360 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
13370 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74  eter to.** xInit
13380 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a   and xShutdown..
13390 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c  **.** SQLite hol
133a0 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
133b0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54  UTEX_STATIC_MAST
133c0 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69  ER] mutex when i
133d0 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65  t invokes.** the
133e0 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73   xInit method, s
133f0 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  o the xInit meth
13400 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74  od need not be t
13410 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a  hreadsafe.  The.
13420 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74  ** xShutdown met
13430 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c  hod is only call
13440 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
13450 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20  _shutdown()] so 
13460 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e  it does.** not n
13470 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64  eed to be thread
13480 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f  safe either.  Fo
13490 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68  r all other meth
134a0 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68  ods, SQLite.** h
134b0 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
134c0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45  _MUTEX_STATIC_ME
134d0 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67  M] mutex as long
134e0 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   as the.** [SQLI
134f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
13500 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  TUS] configurati
13510 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72  on option is tur
13520 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a  ned on (which.**
13530 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c   it is by defaul
13540 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65  t) and so the me
13550 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61  thods are automa
13560 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a  tically serializ
13570 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  ed..** However, 
13580 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  if [SQLITE_CONFI
13590 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20  G_MEMSTATUS] is 
135a0 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74  disabled, then t
135b0 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68  he other.** meth
135c0 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65  ods must be thre
135d0 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d  adsafe or else m
135e0 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72  ake their own ar
135f0 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a  rangements for.*
13600 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e  * serialization.
13610 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69  .**.** SQLite wi
13620 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ll never invoke 
13630 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61  xInit() more tha
13640 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61  n once without a
13650 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a  n intervening.**
13660 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f   call to xShutdo
13670 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  wn()..*/.typedef
13680 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
13690 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  mem_methods sqli
136a0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b  te3_mem_methods;
136b0 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
136c0 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  mem_methods {.  
136d0 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29  void *(*xMalloc)
136e0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f  (int);         /
136f0 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * Memory allocat
13700 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ion function */.
13710 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28    void (*xFree)(
13720 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
13730 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72   /* Free a prior
13740 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
13750 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f   void *(*xReallo
13760 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20  c)(void*,int);  
13770 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c  /* Resize an all
13780 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74  ocation */.  int
13790 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29   (*xSize)(void*)
137a0 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52  ;           /* R
137b0 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f  eturn the size o
137c0 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  f an allocation 
137d0 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e  */.  int (*xRoun
137e0 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20  dup)(int);      
137f0 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20      /* Round up 
13800 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20  request size to 
13810 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
13820 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74  */.  int (*xInit
13830 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
13840 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a      /* Initializ
13850 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
13860 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
13870 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f   (*xShutdown)(vo
13880 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65  id*);      /* De
13890 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  initialize the m
138a0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
138b0 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
138c0 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20  ata;            
138d0 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20      /* Argument 
138e0 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78  to xInit() and x
138f0 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b  Shutdown() */.};
13900 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13910 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  : Configuration 
13920 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f  Options.** KEYWO
13930 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74  RDS: {configurat
13940 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a  ion option}.**.*
13950 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
13960 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
13970 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
13980 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13990 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
139a0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
139b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
139c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
139d0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
139e0 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
139f0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13a00 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
13a10 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
13a20 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
13a30 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
13a40 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
13a50 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
13a60 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
13a70 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
13a80 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
13a90 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
13aa0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  e3_config()] to 
13ab0 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
13ac0 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
13ad0 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  d.  The [sqlite3
13ae0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
13af0 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
13b00 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
13b10 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
13b20 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
13b30 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
13b40 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13b50 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
13b60 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
13b70 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
13b80 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64  INGLETHREAD]] <d
13b90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13ba0 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74  SINGLETHREAD</dt
13bb0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
13bc0 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
13bd0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
13be0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
13bf0 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
13c00 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69  ding mode] to Si
13c10 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e  ngle-thread.  In
13c20 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
13c30 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c   disables.** all
13c40 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75   mutexing and pu
13c50 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61  ts SQLite into a
13c60 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63   mode where it c
13c70 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a  an only be used.
13c80 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74  ** by a single t
13c90 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c  hread.   ^If SQL
13ca0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13cb0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
13cc0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13cd0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13ce0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
13cf0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
13d00 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
13d10 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74  ible to change t
13d20 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  he [threading mo
13d30 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66  de] from its def
13d40 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  ault.** value of
13d50 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61   Single-thread a
13d60 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63  nd so [sqlite3_c
13d70 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
13d80 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  turn .** [SQLITE
13d90 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
13da0 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54  d with the SQLIT
13db0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
13dc0 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75  HREAD.** configu
13dd0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
13de0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13df0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
13e00 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  HREAD]] <dt>SQLI
13e10 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
13e20 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
13e30 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
13e40 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
13e50 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
13e60 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
13e70 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
13e80 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72  de] to Multi-thr
13e90 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ead.  In other w
13ea0 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65  ords, it disable
13eb0 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e  s.** mutexing on
13ec0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13ed0 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
13ee0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
13ef0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20  objects..** The 
13f00 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72  application is r
13f10 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73  esponsible for s
13f20 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73  erializing acces
13f30 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73  s to.** [databas
13f40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
13f50 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
13f60 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f  tements].  But o
13f70 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20  ther mutexes.** 
13f80 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74  are enabled so t
13f90 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  hat SQLite will 
13fa0 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69  be safe to use i
13fb0 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
13fc0 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e  ed.** environmen
13fd0 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20  t as long as no 
13fe0 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65  two threads atte
13ff0 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73  mpt to use the s
14000 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ame.** [database
14010 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20   connection] at 
14020 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20  the same time.  
14030 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
14040 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
14050 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
14060 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
14070 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
14080 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14090 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
140a0 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
140b0 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72  et the Multi-thr
140c0 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  ead [threading m
140d0 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
140e0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
140f0 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
14100 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
14110 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
14120 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
14130 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67  LTITHREAD config
14140 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
14150 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14160 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
14170 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49  LIZED]] <dt>SQLI
14180 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
14190 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  IZED</dt>.** <dd
141a0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
141b0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
141c0 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
141d0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
141e0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
141f0 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64  e] to Serialized
14200 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
14210 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e  , this option en
14220 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
14230 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74  exes including t
14240 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20  he recursive.** 
14250 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61  mutexes on [data
14260 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14270 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
14280 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74  tatement] object
14290 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f  s..** In this mo
142a0 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65  de (which is the
142b0 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51   default when SQ
142c0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
142d0 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45   with.** [SQLITE
142e0 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20  _THREADSAFE=1]) 
142f0 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
14300 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73  ry will itself s
14310 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a  erialize access.
14320 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20  ** to [database 
14330 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
14340 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
14350 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74  ments] so that t
14360 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  he.** applicatio
14370 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65  n is free to use
14380 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62   the same [datab
14390 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
143a0 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b  or the.** same [
143b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
143c0 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74  nt] in different
143d0 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
143e0 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49  same time..** ^I
143f0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
14400 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
14410 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
14420 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
14430 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
14440 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
14450 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
14460 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
14470 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20   the Serialized 
14480 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
14490 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
144a0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
144b0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
144c0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
144d0 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
144e0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
144f0 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69  IZED configurati
14500 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
14510 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14520 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c  ONFIG_MALLOC]] <
14530 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
14540 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20  _MALLOC</dt>.** 
14550 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
14560 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20  E_CONFIG_MALLOC 
14570 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
14580 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
14590 68 69 63 68 20 69 73 20 0a 2a 2a 20 61 20 70 6f  hich is .** a po
145a0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
145b0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
145c0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
145d0 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20  ] structure..** 
145e0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
145f0 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
14600 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
14610 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14620 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  n routines to be
14630 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f   used in place o
14640 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20  f.** the memory 
14650 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
14660 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
14670 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65  QLite.)^ ^SQLite
14680 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77   makes.** its ow
14690 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
146a0 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  f the content of
146b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
146c0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
146d0 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ture.** before t
146e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
146f0 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72  ig()] call retur
14700 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ns.</dd>.**.** [
14710 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
14720 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  ETMALLOC]] <dt>S
14730 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
14740 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
14750 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45  dd> ^(The SQLITE
14760 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
14770 43 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  C option takes a
14780 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
14790 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
147a0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
147b0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
147c0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
147d0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a  s] structure..**
147e0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   The [sqlite3_me
147f0 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74  m_methods].** st
14800 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65  ructure is fille
14810 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  d with the curre
14820 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d  ntly defined mem
14830 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
14840 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
14850 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
14860 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
14870 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65  d the default me
14880 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
14890 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
148a0 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20   a wrapper that 
148b0 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f  simulations memo
148c0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
148d0 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63  ilure or.** trac
148e0 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c  ks memory usage,
148f0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f   for example. </
14900 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14910 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
14920 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TUS]] <dt>SQLITE
14930 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
14940 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  S</dt>.** <dd> ^
14950 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
14960 47 5f 4d 45 4d 53 54 41 54 55 53 20 6f 70 74 69  G_MEMSTATUS opti
14970 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20  on takes single 
14980 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
14990 20 69 6e 74 2c 0a 2a 2a 20 69 6e 74 65 72 70 72   int,.** interpr
149a0 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
149b0 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
149c0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
149d0 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 0a 2a   collection of.*
149e0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
149f0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 2e 20  ion statistics. 
14a00 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
14a10 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
14a20 69 63 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62  ics are.** disab
14a30 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69  led, the followi
14a40 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
14a50 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
14a60 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
14a70 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
14a80 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
14a90 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
14aa0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
14ab0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
14ac0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
14ad0 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
14ae0 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  it64()].**   <li
14af0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
14b00 73 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  s64()].**   </ul
14b10 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
14b20 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
14b30 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
14b40 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
14b50 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
14b60 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
14b70 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
14b80 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
14b90 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
14ba0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
14bb0 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
14bc0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
14bd0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
14be0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14bf0 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
14c00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
14c10 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
14c20 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
14c30 4e 46 49 47 5f 53 43 52 41 54 43 48 20 6f 70 74  NFIG_SCRATCH opt
14c40 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
14c50 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
14c60 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c  ffer.** that SQL
14c70 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 20  ite can use for 
14c80 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20  scratch memory. 
14c90 20 5e 28 54 68 65 72 65 20 61 72 65 20 74 68 72   ^(There are thr
14ca0 65 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  ee arguments.** 
14cb0 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
14cc0 5f 53 43 52 41 54 43 48 3a 20 20 41 20 70 6f 69  _SCRATCH:  A poi
14cd0 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
14ce0 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
14cf0 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
14d00 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
14d10 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
14d20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
14d30 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
14d40 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
14d50 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
14d60 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
14d70 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
14d80 63 61 74 69 6f 6e 73 20 28 4e 29 2e 29 5e 0a 2a  cations (N).)^.*
14d90 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
14da0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
14db0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
14dc0 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
14dd0 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
14de0 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
14df0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
14e00 74 65 20 77 69 6c 6c 20 6e 6f 74 20 75 73 65 20  te will not use 
14e10 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 73 63  more than one sc
14e20 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
14e30 72 20 74 68 72 65 61 64 2e 0a 2a 2a 20 5e 53 51  r thread..** ^SQ
14e40 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
14e50 72 65 71 75 65 73 74 20 61 20 73 63 72 61 74 63  request a scratc
14e60 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
14e70 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
14e80 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
14e90 73 65 20 70 61 67 65 20 73 69 7a 65 2e 0a 2a 2a  se page size..**
14ea0 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
14eb0 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
14ec0 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
14ed0 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
14ee0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
14ef0 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
14f00 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
14f10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
14f20 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
14f30 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
14f40 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
14f50 3c 70 3e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  <p>.** ^When the
14f60 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f   application pro
14f70 76 69 64 65 73 20 61 6e 79 20 61 6d 6f 75 6e 74  vides any amount
14f80 20 6f 66 20 73 63 72 61 74 63 68 20 6d 65 6d 6f   of scratch memo
14f90 72 79 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 49  ry using.** SQLI
14fa0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
14fb0 48 2c 20 53 51 4c 69 74 65 20 61 76 6f 69 64 73  H, SQLite avoids
14fc0 20 75 6e 6e 65 63 65 73 73 61 72 79 20 6c 61 72   unnecessary lar
14fd0 67 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  ge.** [sqlite3_m
14fe0 61 6c 6c 6f 63 7c 68 65 61 70 20 61 6c 6c 6f 63  alloc|heap alloc
14ff0 61 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 69 73  ations]..** This
15000 20 63 61 6e 20 68 65 6c 70 20 5b 52 6f 62 73 6f   can help [Robso
15010 6e 20 70 72 6f 6f 66 7c 70 72 65 76 65 6e 74 20  n proof|prevent 
15020 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
15030 6e 20 66 61 69 6c 75 72 65 73 5d 20 64 75 65 20  n failures] due 
15040 74 6f 20 68 65 61 70 0a 2a 2a 20 66 72 61 67 6d  to heap.** fragm
15050 65 6e 74 61 74 69 6f 6e 20 69 6e 20 6c 6f 77 2d  entation in low-
15060 6d 65 6d 6f 72 79 20 65 6d 62 65 64 64 65 64 20  memory embedded 
15070 73 79 73 74 65 6d 73 2e 0a 2a 2a 20 3c 2f 64 64  systems..** </dd
15080 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15090 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
150a0 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
150b0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
150c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
150d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
150e0 50 41 47 45 43 41 43 48 45 20 6f 70 74 69 6f 6e  PAGECACHE option
150f0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
15100 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
15110 72 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65  r.** that SQLite
15120 20 63 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65   can use for the
15130 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
15140 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
15150 66 61 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61  fault page.** ca
15160 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
15170 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
15180 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
15190 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
151a0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
151b0 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
151c0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
151d0 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
151e0 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
151f0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
15200 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  .** configuratio
15210 6e 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 54 68  n option..** ^Th
15220 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72  ere are three ar
15230 67 75 6d 65 6e 74 73 20 74 6f 20 53 51 4c 49 54  guments to SQLIT
15240 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
15250 48 45 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  HE: A pointer to
15260 0a 2a 2a 20 38 2d 62 79 74 65 20 61 6c 69 67 6e  .** 8-byte align
15270 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  ed.** memory, th
15280 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
15290 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
152a0 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
152b0 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
152c0 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
152d0 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
152e0 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
152f0 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
15300 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
15310 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
15320 61 6e 64 20 36 35 35 33 36 29 20 70 6c 75 73 20  and 65536) plus 
15330 73 6f 6d 65 20 65 78 74 72 61 20 62 79 74 65 73  some extra bytes
15340 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
15350 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
15360 6e 75 6d 62 65 72 20 6f 66 20 65 78 74 72 61 20  number of extra 
15370 62 79 74 65 73 20 6e 65 65 64 65 64 20 62 79 20  bytes needed by 
15380 74 68 65 20 70 61 67 65 20 68 65 61 64 65 72 0a  the page header.
15390 2a 2a 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d  ** can be determ
153a0 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ined using the [
153b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
153c0 41 43 48 45 5f 48 44 52 53 5a 5d 20 6f 70 74 69  ACHE_HDRSZ] opti
153d0 6f 6e 20 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  on .** to [sqlit
153e0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a  e3_config()]..**
153f0 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73   ^It is harmless
15400 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65  , apart from the
15410 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a   wasted memory,.
15420 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70 61  ** for the sz pa
15430 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c 61  rameter to be la
15440 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73 73  rger than necess
15450 61 72 79 2e 20 20 54 68 65 20 66 69 72 73 74 0a  ary.  The first.
15460 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
15470 6c 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e  ld pointer to an
15480 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
15490 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
154a0 74 68 61 74 0a 2a 2a 20 69 73 20 61 74 20 6c 65  that.** is at le
154b0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
154c0 66 20 6d 65 6d 6f 72 79 2c 20 6f 74 68 65 72 77  f memory, otherw
154d0 69 73 65 20 73 75 62 73 65 71 75 65 6e 74 20 62  ise subsequent b
154e0 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
154f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 53 51 4c  defined..** ^SQL
15500 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
15510 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64   memory provided
15520 20 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72   by the first ar
15530 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66  gument to satisf
15540 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20  y its.** memory 
15550 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69  needs for the fi
15560 72 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74  rst N pages that
15570 20 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68   it adds to cach
15580 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e  e.  ^If addition
15590 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  al.** page cache
155a0 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65   memory is neede
155b0 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  d beyond what is
155c0 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
155d0 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a  s option, then.*
155e0 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f  * SQLite goes to
155f0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
15600 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69  ()] for the addi
15610 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73  tional storage s
15620 70 61 63 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  pace.</dd>.**.**
15630 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15640 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
15650 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
15660 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65  dt>.** <dd> ^The
15670 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
15680 45 41 50 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  EAP option speci
15690 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
156a0 6d 6f 72 79 20 62 75 66 66 65 72 20 0a 2a 2a 20  mory buffer .** 
156b0 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
156c0 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
156d0 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  its dynamic memo
156e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
156f0 65 64 73 0a 2a 2a 20 62 65 79 6f 6e 64 20 74 68  eds.** beyond th
15700 6f 73 65 20 70 72 6f 76 69 64 65 64 20 66 6f 72  ose provided for
15710 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   by [SQLITE_CONF
15720 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 0a  IG_SCRATCH] and.
15730 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
15740 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a  G_PAGECACHE]..**
15750 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e   ^The SQLITE_CON
15760 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e 20  FIG_HEAP option 
15770 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c  is only availabl
15780 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63  e if SQLite is c
15790 6f 6d 70 69 6c 65 64 0a 2a 2a 20 77 69 74 68 20  ompiled.** with 
157a0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45  either [SQLITE_E
157b0 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f  NABLE_MEMSYS3] o
157c0 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  r [SQLITE_ENABLE
157d0 5f 4d 45 4d 53 59 53 35 5d 20 61 6e 64 20 72 65  _MEMSYS5] and re
157e0 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
157f0 5f 45 52 52 4f 52 5d 20 69 66 20 69 6e 76 6f 6b  _ERROR] if invok
15800 65 64 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  ed otherwise..**
15810 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72 65   ^There are thre
15820 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 53  e arguments to S
15830 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
15840 50 3a 0a 2a 2a 20 41 6e 20 38 2d 62 79 74 65 20  P:.** An 8-byte 
15850 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
15860 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
15870 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
15880 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
15890 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
158a0 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
158b0 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
158c0 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
158d0 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
158e0 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
158f0 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
15900 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
15910 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
15920 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
15930 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
15940 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
15950 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
15960 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
15970 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
15980 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
15990 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
159a0 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
159b0 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68  not NULL then th
159c0 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
159d0 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
159e0 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
159f0 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
15a00 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
15a10 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
15a20 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
15a30 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
15a40 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
15a50 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
15a60 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
15a70 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
15a80 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
15a90 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
15aa0 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
15ab0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
15ac0 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
15ad0 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61  t 2**12. Reasona
15ae0 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f  ble values.** fo
15af0 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  r the minimum al
15b00 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72  location size ar
15b10 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32  e 2**5 through 2
15b20 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  **8.</dd>.**.** 
15b30 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15b40 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49  MUTEX]] <dt>SQLI
15b50 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
15b60 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
15b70 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
15b80 5f 4d 55 54 45 58 20 6f 70 74 69 6f 6e 20 74 61  _MUTEX option ta
15b90 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15ba0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
15bb0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  .** pointer to a
15bc0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
15bd0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
15be0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15bf0 75 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75  ure..** The argu
15c00 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 20 61  ment specifies a
15c10 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
15c20 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
15c30 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 0a 2a  nes to be used.*
15c40 2a 20 69 6e 20 70 6c 61 63 65 20 74 68 65 20 6d  * in place the m
15c50 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
15c60 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
15c70 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
15c80 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
15c90 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
15ca0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
15cb0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
15cc0 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
15cd0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
15ce0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
15cf0 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
15d00 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
15d10 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
15d20 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
15d30 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
15d40 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
15d50 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
15d60 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
15d70 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
15d80 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
15d90 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
15da0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
15db0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
15dc0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
15dd0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
15de0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15df0 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
15e00 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
15e10 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15e20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15e30 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
15e40 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
15e50 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
15e60 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
15e70 49 47 5f 47 45 54 4d 55 54 45 58 20 6f 70 74 69  IG_GETMUTEX opti
15e80 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
15e90 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
15ea0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
15eb0 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
15ec0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
15ed0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
15ee0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
15ef0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
15f00 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
15f10 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
15f20 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
15f30 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
15f40 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
15f50 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
15f60 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
15f70 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
15f80 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
15f90 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
15fa0 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
15fb0 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
15fc0 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
15fd0 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
15fe0 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
15ff0 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
16000 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
16010 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
16020 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
16030 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
16040 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
16050 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
16060 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
16070 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
16080 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
16090 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
160a0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
160b0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
160c0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
160d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
160e0 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
160f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
16100 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
16110 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
16120 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16130 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
16140 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
16150 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
16160 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
16170 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16180 5f 4c 4f 4f 4b 41 53 49 44 45 20 6f 70 74 69 6f  _LOOKASIDE optio
16190 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
161a0 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
161b0 6d 69 6e 65 0a 2a 2a 20 74 68 65 20 64 65 66 61  mine.** the defa
161c0 75 6c 74 20 73 69 7a 65 20 6f 66 20 6c 6f 6f 6b  ult size of look
161d0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 6f 6e 20  aside memory on 
161e0 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20 63  each [database c
161f0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 54  onnection]..** T
16200 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16210 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
16220 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
16230 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
16240 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
16250 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
16260 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
16270 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
16280 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
16290 20 20 5e 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49    ^(SQLITE_CONFI
162a0 47 5f 4c 4f 4f 4b 41 53 49 44 45 0a 2a 2a 20 73  G_LOOKASIDE.** s
162b0 65 74 73 20 74 68 65 20 3c 69 3e 64 65 66 61 75  ets the <i>defau
162c0 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
162d0 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
162e0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
162f0 41 53 49 44 45 5d 0a 2a 2a 20 6f 70 74 69 6f 6e  ASIDE].** option
16300 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
16310 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65  config()] can be
16320 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20   used to change 
16330 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a  the lookaside.**
16340 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
16350 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e  n individual con
16360 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64  nections.)^ </dd
16370 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16380 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d  _CONFIG_PCACHE2]
16390 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
163a0 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e  FIG_PCACHE2</dt>
163b0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53  .** <dd> ^(The S
163c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
163d0 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b 65  CHE2 option take
163e0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
163f0 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a 2a  ent which is .**
16400 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16410 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
16420 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
16430 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
16440 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
16450 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 61 20   interface to a 
16460 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
16470 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
16480 2e 29 5e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 6d  .)^.** ^SQLite m
16490 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
164a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  he [sqlite3_pcac
164b0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
164c0 65 63 74 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ect.</dd>.**.** 
164d0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
164e0 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  GETPCACHE2]] <dt
164f0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
16500 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  ETPCACHE2</dt>.*
16510 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c  * <dd> ^(The SQL
16520 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
16530 41 43 48 45 32 20 6f 70 74 69 6f 6e 20 74 61 6b  ACHE2 option tak
16540 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
16550 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20 69 73  ment which.** is
16560 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16570 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
16580 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
16590 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65  t.  SQLite copie
165a0 73 20 6f 66 0a 2a 2a 20 74 68 65 20 63 75 72 72  s of.** the curr
165b0 65 6e 74 20 70 61 67 65 20 63 61 63 68 65 20 69  ent page cache i
165c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
165d0 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29  to that object.)
165e0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
165f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
16600 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  G]] <dt>SQLITE_C
16610 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a  ONFIG_LOG</dt>.*
16620 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54  * <dd> The SQLIT
16630 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
16640 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63  ion is used to c
16650 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51 4c  onfigure the SQL
16660 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65  ite.** global [e
16670 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e  rror log]..** (^
16680 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16690 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
166a0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
166b0 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
166c0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
166d0 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
166e0 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
166f0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
16700 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
16710 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
16720 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
16730 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
16740 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
16750 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
16760 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
16770 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
16780 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
16790 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
167a0 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
167b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
167c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
167d0 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
167e0 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
167f0 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
16800 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
16810 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
16820 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
16830 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
16840 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
16850 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
16860 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
16870 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
16880 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
16890 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
168a0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
168b0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
168c0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
168d0 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
168e0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
168f0 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
16900 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
16910 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
16920 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
16930 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
16940 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
16950 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
16960 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
16970 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
16980 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
16990 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
169a0 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
169b0 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
169c0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
169d0 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
169e0 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
169f0 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
16a00 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
16a10 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
16a20 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
16a30 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
16a40 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
16a50 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
16a60 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
16a70 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
16a80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
16a90 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
16aa0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
16ab0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
16ac0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
16ad0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
16ae0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16af0 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54  G_URI.** <dd>^(T
16b00 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16b10 5f 55 52 49 20 6f 70 74 69 6f 6e 20 74 61 6b 65  _URI option take
16b20 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
16b30 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
16b40 0a 2a 2a 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  .** If non-zero,
16b50 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
16b60 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
16b70 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
16b80 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
16b90 2c 0a 2a 2a 20 74 68 65 6e 20 55 52 49 20 68 61  ,.** then URI ha
16ba0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
16bb0 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
16bc0 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
16bd0 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 65  is globally.** e
16be0 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65  nabled, all file
16bf0 6e 61 6d 65 73 20 70 61 73 73 65 64 20 74 6f 20  names passed to 
16c00 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
16c10 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
16c20 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  v2()],.** [sqlit
16c30 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a  e3_open16()] or.
16c40 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ** specified as 
16c50 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d  part of [ATTACH]
16c60 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e   commands are in
16c70 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
16c80 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a  s, regardless.**
16c90 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
16ca0 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ot the [SQLITE_O
16cb0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
16cc0 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61   set when the da
16cd0 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
16ce0 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
16cf0 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c  ^If it is global
16d00 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c  ly disabled, fil
16d10 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e  enames are.** on
16d20 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  ly interpreted a
16d30 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53 51  s URIs if the SQ
16d40 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c  LITE_OPEN_URI fl
16d50 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74  ag is set when t
16d60 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  he.** database c
16d70 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65  onnection is ope
16d80 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75 6c  ned. ^(By defaul
16d90 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  t, URI handling 
16da0 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64  is globally.** d
16db0 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66  isabled. The def
16dc0 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62  ault value may b
16dd0 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d  e changed by com
16de0 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a  piling with the.
16df0 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  ** [SQLITE_USE_U
16e00 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e  RI] symbol defin
16e10 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ed.)^.**.** [[SQ
16e20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
16e30 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d  RING_INDEX_SCAN]
16e40 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16e50 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
16e60 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e  EX_SCAN.** <dd>^
16e70 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
16e80 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
16e90 5f 53 43 41 4e 20 6f 70 74 69 6f 6e 20 74 61 6b  _SCAN option tak
16ea0 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
16eb0 67 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ger.** argument 
16ec0 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
16ed0 65 74 65 64 20 61 73 20 61 20 62 6f 6f 6c 65 61  eted as a boolea
16ee0 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
16ef0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 0a  able or disable.
16f00 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  ** the use of co
16f10 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
16f20 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  or full table sc
16f30 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
16f40 20 6f 70 74 69 6d 69 7a 65 72 2e 0a 2a 2a 20 5e   optimizer..** ^
16f50 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
16f60 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
16f70 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
16f80 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
16f90 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
16fa0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
16fb0 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
16fc0 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
16fd0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
16fe0 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
16ff0 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
17000 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
17010 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
17020 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
17030 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
17040 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
17050 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
17060 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
17070 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
17080 2a 2a 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69  ** when the opti
17090 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  mization is enab
170a0 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20  led.  Providing 
170b0 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a  the ability to.*
170c0 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70  * disable the op
170d0 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77  timization allow
170e0 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67  s the older, bug
170f0 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  gy application c
17100 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ode to work.** w
17110 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76  ithout change ev
17120 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65  en with newer ve
17130 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
17140 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ..**.** [[SQLITE
17150 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d  _CONFIG_PCACHE]]
17160 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
17170 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20  _GETPCACHE]].** 
17180 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17190 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c  G_PCACHE and SQL
171a0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
171b0 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  ACHE.** <dd> The
171c0 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f  se options are o
171d0 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75  bsolete and shou
171e0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62  ld not be used b
171f0 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54  y new code..** T
17200 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64  hey are retained
17210 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
17220 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74  ompatibility but
17230 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e   are now no-ops.
17240 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
17250 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
17260 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e  SQLLOG]].** <dt>
17270 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
17280 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73  LLOG.** <dd>This
17290 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20   option is only 
172a0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c  available if sql
172b0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
172c0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
172d0 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f  ITE_ENABLE_SQLLO
172e0 47 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  G] pre-processor
172f0 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
17300 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
17310 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
17320 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
17330 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
17340 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
17350 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
17360 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
17370 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
17380 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
17390 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
173a0 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
173b0 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
173c0 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
173d0 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
173e0 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
173f0 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
17400 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
17410 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
17420 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
17430 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
17440 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17450 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
17460 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
17470 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
17480 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
17490 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
174a0 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
174b0 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
174c0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
174d0 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
174e0 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
174f0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
17500 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
17510 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
17520 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
17530 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
17540 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
17550 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
17560 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
17570 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
17580 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
17590 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
175a0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
175b0 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
175c0 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
175d0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
175e0 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
175f0 20 74 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20   this case.  An 
17600 65 78 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67  example of using
17610 20 74 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75   this.** configu
17620 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61  ration option ca
17630 6e 20 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65  n be seen in the
17640 20 22 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22   "test_sqllog.c"
17650 20 73 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a   source file in.
17660 2a 2a 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c  ** the canonical
17670 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
17680 72 65 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ree.</dd>.**.** 
17690 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
176a0 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  MMAP_SIZE]].** <
176b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
176c0 5f 4d 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64  _MMAP_SIZE.** <d
176d0 64 3e 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  d>^SQLITE_CONFIG
176e0 5f 4d 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73  _MMAP_SIZE takes
176f0 20 74 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65   two 64-bit inte
17700 67 65 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74  ger (sqlite3_int
17710 36 34 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  64) values.** th
17720 61 74 20 61 72 65 20 74 68 65 20 64 65 66 61 75  at are the defau
17730 6c 74 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d  lt mmap size lim
17740 69 74 20 28 74 68 65 20 64 65 66 61 75 6c 74 20  it (the default 
17750 73 65 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b  setting for.** [
17760 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65  PRAGMA mmap_size
17770 5d 29 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ]) and the maxim
17780 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20  um allowed mmap 
17790 73 69 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e  size limit..** ^
177a0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
177b0 69 6e 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72  ing can be overr
177c0 69 64 64 65 6e 20 62 79 20 65 61 63 68 20 64 61  idden by each da
177d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
177e0 6e 20 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65  n using.** eithe
177f0 72 20 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d  r the [PRAGMA mm
17800 61 70 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64  ap_size] command
17810 2c 20 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68  , or by using th
17820 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
17830 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69  TL_MMAP_SIZE] fi
17840 6c 65 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54  le control.  ^(T
17850 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
17860 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
17870 77 69 6c 6c 20 62 65 20 73 69 6c 65 6e 74 6c 79  will be silently
17880 20 74 72 75 6e 63 61 74 65 64 20 69 66 20 6e 65   truncated if ne
17890 63 65 73 73 61 72 79 20 73 6f 20 74 68 61 74 20  cessary so that 
178a0 69 74 20 64 6f 65 73 20 6e 6f 74 20 65 78 63 65  it does not exce
178b0 65 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  ed the.** compil
178c0 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d  e-time maximum m
178d0 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20  map size set by 
178e0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  the.** [SQLITE_M
178f0 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f  AX_MMAP_SIZE] co
17900 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
17910 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68  n.)^.** ^If eith
17920 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  er argument to t
17930 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65  his option is ne
17940 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61  gative, then tha
17950 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  t argument is.**
17960 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20   changed to its 
17970 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66  compile-time def
17980 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  ault..**.** [[SQ
17990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
179a0 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20  2_HEAPSIZE]].** 
179b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
179c0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
179d0 0a 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c  .** <dd>^The SQL
179e0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
179f0 5f 48 45 41 50 53 49 5a 45 20 6f 70 74 69 6f 6e  _HEAPSIZE option
17a00 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
17a10 6c 65 20 69 66 20 53 51 4c 69 74 65 20 69 73 0a  le if SQLite is.
17a20 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  ** compiled for 
17a30 57 69 6e 64 6f 77 73 20 77 69 74 68 20 74 68 65  Windows with the
17a40 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d   [SQLITE_WIN32_M
17a50 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72 6f 63 65  ALLOC] pre-proce
17a60 73 73 6f 72 20 6d 61 63 72 6f 0a 2a 2a 20 64 65  ssor macro.** de
17a70 66 69 6e 65 64 2e 20 5e 53 51 4c 49 54 45 5f 43  fined. ^SQLITE_C
17a80 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
17a90 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33 32 2d  SIZE takes a 32-
17aa0 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74  bit unsigned int
17ab0 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20 74 68  eger value.** th
17ac0 61 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65  at specifies the
17ad0 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
17ae0 20 74 68 65 20 63 72 65 61 74 65 64 20 68 65 61   the created hea
17af0 70 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  p..**.** [[SQLIT
17b00 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f  E_CONFIG_PCACHE_
17b10 48 44 52 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  HDRSZ]].** <dt>S
17b20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17b30 43 48 45 5f 48 44 52 53 5a 0a 2a 2a 20 3c 64 64  CHE_HDRSZ.** <dd
17b40 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17b50 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
17b60 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17b70 73 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72  single parameter
17b80 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
17b90 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
17ba0 65 67 65 72 20 61 6e 64 20 77 72 69 74 65 73 20  eger and writes 
17bb0 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
17bc0 72 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  r the number of 
17bd0 65 78 74 72 61 0a 2a 2a 20 62 79 74 65 73 20 70  extra.** bytes p
17be0 65 72 20 70 61 67 65 20 72 65 71 75 69 72 65 64  er page required
17bf0 20 66 6f 72 20 65 61 63 68 20 70 61 67 65 20 69   for each page i
17c00 6e 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  n [SQLITE_CONFIG
17c10 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20  _PAGECACHE]..** 
17c20 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 65 78  The amount of ex
17c30 74 72 61 20 73 70 61 63 65 20 72 65 71 75 69 72  tra space requir
17c40 65 64 20 63 61 6e 20 63 68 61 6e 67 65 20 64 65  ed can change de
17c50 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
17c60 6f 6d 70 69 6c 65 72 2c 0a 2a 2a 20 74 61 72 67  ompiler,.** targ
17c70 65 74 20 70 6c 61 74 66 6f 72 6d 2c 20 61 6e 64  et platform, and
17c80 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 2e   SQLite version.
17c90 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17ca0 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 5d 5d 0a 2a  CONFIG_PMASZ]].*
17cb0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17cc0 46 49 47 5f 50 4d 41 53 5a 0a 2a 2a 20 3c 64 64  FIG_PMASZ.** <dd
17cd0 3e 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  >^The SQLITE_CON
17ce0 46 49 47 5f 50 4d 41 53 5a 20 6f 70 74 69 6f 6e  FIG_PMASZ option
17cf0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
17d00 70 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a  parameter which.
17d10 2a 2a 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65  ** is an unsigne
17d20 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 73 65  d integer and se
17d30 74 73 20 74 68 65 20 22 4d 69 6e 69 6d 75 6d 20  ts the "Minimum 
17d40 50 4d 41 20 53 69 7a 65 22 20 66 6f 72 20 74 68  PMA Size" for th
17d50 65 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 0a  e multithreaded.
17d60 2a 2a 20 73 6f 72 74 65 72 20 74 6f 20 74 68 61  ** sorter to tha
17d70 74 20 69 6e 74 65 67 65 72 2e 20 20 54 68 65 20  t integer.  The 
17d80 64 65 66 61 75 6c 74 20 6d 69 6e 69 6d 75 6d 20  default minimum 
17d90 50 4d 41 20 53 69 7a 65 20 69 73 20 73 65 74 20  PMA Size is set 
17da0 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  by the.** [SQLIT
17db0 45 5f 53 4f 52 54 45 52 5f 50 4d 41 53 5a 5d 20  E_SORTER_PMASZ] 
17dc0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
17dd0 69 6f 6e 2e 20 20 4e 65 77 20 74 68 72 65 61 64  ion.  New thread
17de0 73 20 61 72 65 20 6c 61 75 6e 63 68 65 64 0a 2a  s are launched.*
17df0 2a 20 74 6f 20 68 65 6c 70 20 77 69 74 68 20 73  * to help with s
17e00 6f 72 74 20 6f 70 65 72 61 74 69 6f 6e 73 20 77  ort operations w
17e10 68 65 6e 20 6d 75 6c 74 69 74 68 72 65 61 64 65  hen multithreade
17e20 64 20 73 6f 72 74 69 6e 67 0a 2a 2a 20 69 73 20  d sorting.** is 
17e30 65 6e 61 62 6c 65 64 20 28 75 73 69 6e 67 20 74  enabled (using t
17e40 68 65 20 5b 50 52 41 47 4d 41 20 74 68 72 65 61  he [PRAGMA threa
17e50 64 73 5d 20 63 6f 6d 6d 61 6e 64 29 20 61 6e 64  ds] command) and
17e60 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 63   the amount of c
17e70 6f 6e 74 65 6e 74 0a 2a 2a 20 74 6f 20 62 65 20  ontent.** to be 
17e80 73 6f 72 74 65 64 20 65 78 63 65 65 64 73 20 74  sorted exceeds t
17e90 68 65 20 70 61 67 65 20 73 69 7a 65 20 74 69 6d  he page size tim
17ea0 65 73 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6f  es the minimum o
17eb0 66 20 74 68 65 0a 2a 2a 20 5b 50 52 41 47 4d 41  f the.** [PRAGMA
17ec0 20 63 61 63 68 65 5f 73 69 7a 65 5d 20 73 65 74   cache_size] set
17ed0 74 69 6e 67 20 61 6e 64 20 74 68 69 73 20 76 61  ting and this va
17ee0 6c 75 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  lue..** </dl>.*/
17ef0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17f00 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
17f10 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
17f20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17f30 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
17f40 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
17f50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17f60 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
17f70 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
17f80 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17f90 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
17fa0 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
17fb0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
17fc0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
17fd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
17fe0 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
17ff0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
18000 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
18010 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
18020 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
18030 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
18040 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
18050 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18060 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
18070 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
18080 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
18090 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
180a0 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
180b0 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
180c0 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
180d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
180e0 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
180f0 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
18100 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
18110 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
18120 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
18130 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
18140 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
18150 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18160 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
18170 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
18180 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
18190 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
181a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
181b0 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
181c0 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
181d0 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
181e0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
181f0 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
18200 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
18210 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
18220 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
18230 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
18240 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18250 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
18260 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
18270 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18280 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
18290 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
182a0 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
182b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
182c0 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
182d0 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
182e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
182f0 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
18300 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
18310 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
18320 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18330 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
18340 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
18350 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
18360 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18370 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
18380 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
18390 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
183a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
183b0 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
183c0 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
183d0 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
183e0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
183f0 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
18400 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
18410 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
18420 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18430 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
18440 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
18450 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
18460 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18470 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5f 48 44  CONFIG_PCACHE_HD
18480 52 53 5a 20 20 20 20 20 20 20 20 32 34 20 20 2f  RSZ        24  /
18490 2a 20 69 6e 74 20 2a 70 73 7a 20 2a 2f 0a 23 64  * int *psz */.#d
184a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
184b0 46 49 47 5f 50 4d 41 53 5a 20 20 20 20 20 20 20  FIG_PMASZ       
184c0 20 20 20 20 20 20 20 20 32 35 20 20 2f 2a 20 75          25  /* u
184d0 6e 73 69 67 6e 65 64 20 69 6e 74 20 73 7a 50 6d  nsigned int szPm
184e0 61 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a */../*.** CAPI
184f0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
18500 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
18510 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
18520 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
18530 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
18540 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
18550 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
18560 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
18570 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
18580 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18590 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
185a0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
185b0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
185c0 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
185d0 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
185e0 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
185f0 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
18600 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
18610 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
18620 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
18630 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
18640 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
18650 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
18660 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
18670 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
18680 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
18690 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
186a0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
186b0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
186c0 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
186d0 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
186e0 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
186f0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
18700 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
18710 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
18720 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
18730 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
18740 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
18750 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
18760 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
18770 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
18780 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
18790 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
187a0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
187b0 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
187c0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
187d0 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
187e0 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
187f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
18800 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
18810 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
18820 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
18830 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
18840 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
18850 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
18860 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
18870 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
18880 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
18890 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
188a0 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
188b0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
188c0 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
188d0 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
188e0 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
188f0 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
18900 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
18910 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
18920 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
18930 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
18940 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
18950 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
18960 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
18970 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
18980 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
18990 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
189a0 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
189b0 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
189c0 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
189d0 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
189e0 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
189f0 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
18a00 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
18a10 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
18a20 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
18a30 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
18a40 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
18a50 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
18a60 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
18a70 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
18a80 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18a90 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
18aa0 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
18ab0 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
18ac0 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
18ad0 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
18ae0 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
18af0 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
18b00 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
18b10 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
18b20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
18b30 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
18b40 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
18b50 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
18b60 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
18b70 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
18b80 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
18b90 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
18ba0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
18bb0 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
18bc0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
18bd0 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
18be0 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
18bf0 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
18c00 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
18c10 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
18c20 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
18c30 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
18c40 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
18c50 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
18c60 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
18c70 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
18c80 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
18c90 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
18ca0 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
18cb0 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
18cc0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18cd0 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
18ce0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
18cf0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
18d00 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
18d10 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
18d20 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
18d30 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
18d40 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
18d50 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
18d60 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
18d70 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18d80 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
18d90 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
18da0 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
18db0 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
18dc0 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
18dd0 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
18de0 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
18df0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
18e00 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
18e10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18e20 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
18e30 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
18e40 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
18e50 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
18e60 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
18e70 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
18e80 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
18e90 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
18ea0 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
18eb0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
18ec0 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
18ed0 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
18ee0 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
18ef0 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
18f00 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
18f10 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
18f20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
18f30 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
18f40 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
18f50 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
18f60 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
18f70 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
18f80 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
18f90 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
18fa0 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
18fb0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
18fc0 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
18fd0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
18fe0 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
18ff0 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
19000 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
19010 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
19020 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
19030 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
19040 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
19050 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
19060 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19070 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19080 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19090 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
190a0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
190b0 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
190c0 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
190d0 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
190e0 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
190f0 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
19100 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
19110 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
19120 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
19130 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
19140 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
19150 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
19160 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
19170 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19180 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
19190 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a  E       1001  /*
191a0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
191b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
191c0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
191d0 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20  _FKEY     1002  
191e0 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
191f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
19200 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
19210 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20  IGGER  1003  /* 
19220 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
19230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
19240 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
19250 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
19260 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Codes.** METHOD:
19270 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
19280 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
19290 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
192a0 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
192b0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
192c0 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
192d0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
192e0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
192f0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
19300 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
19310 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
19320 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
19330 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
19340 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lity..*/.SQLITE_
19350 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
19360 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
19370 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63  xtended_result_c
19380 6f 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69  odes(sqlite3*, i
19390 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
193a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74  * CAPI3REF: Last
193b0 20 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a   Insert Rowid.**
193c0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
193d0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
193e0 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69 74  ry in most SQLit
193f0 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70 74  e tables (except
19400 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52 4f   for [WITHOUT RO
19410 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a 20  WID] tables).** 
19420 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
19430 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
19440 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
19450 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
19460 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
19470 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
19480 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
19490 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
194a0 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
194b0 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
194c0 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
194d0 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
194e0 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
194f0 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
19500 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
19510 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
19520 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
19530 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
19540 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
19550 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
19560 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
19570 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
19580 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 61   ^The sqlite3_la
19590 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
195a0 44 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  D) interface ret
195b0 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  urns the [rowid]
195c0 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73 74   of the .** most
195d0 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73 66   recent successf
195e0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f  ul [INSERT] into
195f0 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20 6f   a rowid table o
19600 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  r [virtual table
19610 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73 65  ].** on database
19620 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a   connection D..*
19630 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f 20  * ^Inserts into 
19640 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20  [WITHOUT ROWID] 
19650 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20 72  tables are not r
19660 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66 20  ecorded..** ^If 
19670 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
19680 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f 77  NSERT]s into row
19690 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61 76  id tables.** hav
196a0 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
196b0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
196c0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a 2a  connection D, .*
196d0 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6c  * then sqlite3_l
196e0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
196f0 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  (D) returns zero
19700 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
19710 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
19720 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
19730 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69   or within a [vi
19740 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
19750 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69  method, then thi
19760 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  s routine will r
19770 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
19780 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
19790 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67  d.** row as long
197a0 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
197b0 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
197c0 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69   method is runni
197d0 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
197e0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
197f0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
19800 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61  hod ends, the va
19810 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
19820 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
19830 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
19840 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
19850 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
19860 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d  rtual.** table m
19870 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a  ethod began.)^.*
19880 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
19890 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
198a0 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
198b0 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
198c0 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
198d0 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
198e0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
198f0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19900 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
19910 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
19920 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
19930 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
19940 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
19950 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
19960 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
19970 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
19980 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
19990 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
199a0 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
199b0 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
199c0 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
199d0 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
199e0 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
199f0 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
19a00 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
19a10 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
19a20 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
19a30 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
19a40 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
19a50 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
19a60 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
19a70 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
19a80 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
19a90 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
19aa0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
19ab0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
19ac0 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
19ad0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
19ae0 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
19af0 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
19b00 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
19b10 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
19b20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
19b30 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
19b40 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
19b50 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
19b60 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
19b70 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
19b80 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19b90 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
19ba0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
19bb0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
19bc0 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
19bd0 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
19be0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
19bf0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
19c00 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
19c10 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19c20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
19c30 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
19c40 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
19c50 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
19c60 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
19c70 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
19c80 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
19c90 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
19ca0 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
19cb0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
19cc0 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
19cd0 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
19ce0 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
19cf0 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  rowid]..*/.SQLIT
19d00 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
19d10 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41  t64 SQLITE_STDCA
19d20 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  LL sqlite3_last_
19d30 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c  insert_rowid(sql
19d40 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
19d50 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54  API3REF: Count T
19d60 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  he Number Of Row
19d70 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45  s Modified.** ME
19d80 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
19d90 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
19da0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
19db0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f  umber of rows mo
19dc0 64 69 66 69 65 64 2c 20 69 6e 73 65 72 74 65 64  dified, inserted
19dd0 20 6f 72 0a 2a 2a 20 64 65 6c 65 74 65 64 20 62   or.** deleted b
19de0 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
19df0 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e  tly completed IN
19e00 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
19e10 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
19e20 65 6e 74 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ent on the datab
19e30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
19e40 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
19e50 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  only parameter..
19e60 2a 2a 20 5e 45 78 65 63 75 74 69 6e 67 20 61 6e  ** ^Executing an
19e70 79 20 6f 74 68 65 72 20 74 79 70 65 20 6f 66 20  y other type of 
19e80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  SQL statement do
19e90 65 73 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  es not modify th
19ea0 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
19eb0 6e 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63  ned by this func
19ec0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c  tion..**.** ^Onl
19ed0 79 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 64  y changes made d
19ee0 69 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 49  irectly by the I
19ef0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72  NSERT, UPDATE or
19f00 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
19f10 74 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  t are.** conside
19f20 72 65 64 20 2d 20 61 75 78 69 6c 69 61 72 79 20  red - auxiliary 
19f30 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
19f40 79 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  y [CREATE TRIGGE
19f50 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2c 20 0a  R | triggers], .
19f60 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
19f70 61 63 74 69 6f 6e 73 5d 20 6f 72 20 5b 52 45 50  actions] or [REP
19f80 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
19f90 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61 72 65 20   resolution are 
19fa0 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20  not counted..** 
19fb0 0a 2a 2a 20 43 68 61 6e 67 65 73 20 74 6f 20 61  .** Changes to a
19fc0 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 69   view that are i
19fd0 6e 74 65 72 63 65 70 74 65 64 20 62 79 20 0a 2a  ntercepted by .*
19fe0 2a 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  * [INSTEAD OF tr
19ff0 69 67 67 65 72 20 7c 20 49 4e 53 54 45 41 44 20  igger | INSTEAD 
1a000 4f 46 20 74 72 69 67 67 65 72 73 5d 20 61 72 65  OF triggers] are
1a010 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 5e 54   not counted. ^T
1a020 68 65 20 76 61 6c 75 65 20 0a 2a 2a 20 72 65 74  he value .** ret
1a030 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1a040 5f 63 68 61 6e 67 65 73 28 29 20 69 6d 6d 65 64  _changes() immed
1a050 69 61 74 65 6c 79 20 61 66 74 65 72 20 61 6e 20  iately after an 
1a060 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1a070 72 20 0a 2a 2a 20 44 45 4c 45 54 45 20 73 74 61  r .** DELETE sta
1a080 74 65 6d 65 6e 74 20 72 75 6e 20 6f 6e 20 61 20  tement run on a 
1a090 76 69 65 77 20 69 73 20 61 6c 77 61 79 73 20 7a  view is always z
1a0a0 65 72 6f 2e 20 4f 6e 6c 79 20 63 68 61 6e 67 65  ero. Only change
1a0b0 73 20 6d 61 64 65 20 74 6f 20 72 65 61 6c 20 0a  s made to real .
1a0c0 2a 2a 20 74 61 62 6c 65 73 20 61 72 65 20 63 6f  ** tables are co
1a0d0 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  unted..**.** Thi
1a0e0 6e 67 73 20 61 72 65 20 6d 6f 72 65 20 63 6f 6d  ngs are more com
1a0f0 70 6c 69 63 61 74 65 64 20 69 66 20 74 68 65 20  plicated if the 
1a100 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
1a110 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  ) function is.**
1a120 20 65 78 65 63 75 74 65 64 20 77 68 69 6c 65 20   executed while 
1a130 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61  a trigger progra
1a140 6d 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 54 68  m is running. Th
1a150 69 73 20 6d 61 79 20 68 61 70 70 65 6e 20 69 66  is may happen if
1a160 20 74 68 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20   the.** program 
1a170 75 73 65 73 20 74 68 65 20 5b 63 68 61 6e 67 65  uses the [change
1a180 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1a190 5d 2c 20 6f 72 20 69 66 20 73 6f 6d 65 20 6f 74  ], or if some ot
1a1a0 68 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  her callback.** 
1a1b0 66 75 6e 63 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  function invokes
1a1c0 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1a1d0 28 29 20 64 69 72 65 63 74 6c 79 2e 20 45 73 73  () directly. Ess
1a1e0 65 6e 74 69 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a  entially:.** .**
1a1f0 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
1a200 5e 28 42 65 66 6f 72 65 20 65 6e 74 65 72 69 6e  ^(Before enterin
1a210 67 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67  g a trigger prog
1a220 72 61 6d 20 74 68 65 20 76 61 6c 75 65 20 72 65  ram the value re
1a230 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 20 20 20  turned by.**    
1a240 20 20 20 20 73 71 6c 69 74 65 33 5f 63 68 61 6e      sqlite3_chan
1a250 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ges() function i
1a260 73 20 73 61 76 65 64 2e 20 41 66 74 65 72 20 74  s saved. After t
1a270 68 65 20 74 72 69 67 67 65 72 20 70 72 6f 67 72  he trigger progr
1a280 61 6d 20 0a 2a 2a 20 20 20 20 20 20 20 20 68 61  am .**        ha
1a290 73 20 66 69 6e 69 73 68 65 64 2c 20 74 68 65 20  s finished, the 
1a2a0 6f 72 69 67 69 6e 61 6c 20 76 61 6c 75 65 20 69  original value i
1a2b0 73 20 72 65 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a  s restored.)^.**
1a2c0 20 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 57 69   .**   <li> ^(Wi
1a2d0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 70  thin a trigger p
1a2e0 72 6f 67 72 61 6d 20 65 61 63 68 20 49 4e 53 45  rogram each INSE
1a2f0 52 54 2c 20 55 50 44 41 54 45 20 61 6e 64 20 44  RT, UPDATE and D
1a300 45 4c 45 54 45 20 0a 2a 2a 20 20 20 20 20 20 20  ELETE .**       
1a310 20 73 74 61 74 65 6d 65 6e 74 20 73 65 74 73 20   statement sets 
1a320 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1a330 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68  ed by sqlite3_ch
1a340 61 6e 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20  anges() .**     
1a350 20 20 20 75 70 6f 6e 20 63 6f 6d 70 6c 65 74 69     upon completi
1a360 6f 6e 20 61 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66  on as normal. Of
1a370 20 63 6f 75 72 73 65 2c 20 74 68 69 73 20 76 61   course, this va
1a380 6c 75 65 20 77 69 6c 6c 20 6e 6f 74 20 69 6e 63  lue will not inc
1a390 6c 75 64 65 20 0a 2a 2a 20 20 20 20 20 20 20 20  lude .**        
1a3a0 61 6e 79 20 63 68 61 6e 67 65 73 20 70 65 72 66  any changes perf
1a3b0 6f 72 6d 65 64 20 62 79 20 73 75 62 2d 74 72 69  ormed by sub-tri
1a3c0 67 67 65 72 73 2c 20 61 73 20 74 68 65 20 73 71  ggers, as the sq
1a3d0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
1a3e0 0a 2a 2a 20 20 20 20 20 20 20 20 76 61 6c 75 65  .**        value
1a3f0 20 77 69 6c 6c 20 62 65 20 73 61 76 65 64 20 61   will be saved a
1a400 6e 64 20 72 65 73 74 6f 72 65 64 20 61 66 74 65  nd restored afte
1a410 72 20 65 61 63 68 20 73 75 62 2d 74 72 69 67 67  r each sub-trigg
1a420 65 72 20 68 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a  er has run.)^.**
1a430 20 3c 2f 75 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54   </ul>.** .** ^T
1a440 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 69  his means that i
1a450 66 20 74 68 65 20 63 68 61 6e 67 65 73 28 29 20  f the changes() 
1a460 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 28 6f 72  SQL function (or
1a470 20 73 69 6d 69 6c 61 72 29 20 69 73 20 75 73 65   similar) is use
1a480 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72 73  d.** by the firs
1a490 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
1a4a0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
1a4b0 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74 72  ment within a tr
1a4c0 69 67 67 65 72 2c 20 69 74 20 0a 2a 2a 20 72 65  igger, it .** re
1a4d0 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
1a4e0 61 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  as set when the 
1a4f0 63 61 6c 6c 69 6e 67 20 73 74 61 74 65 6d 65 6e  calling statemen
1a500 74 20 62 65 67 61 6e 20 65 78 65 63 75 74 69 6e  t began executin
1a510 67 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20  g..** ^If it is 
1a520 75 73 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  used by the seco
1a530 6e 64 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  nd or subsequent
1a540 20 73 75 63 68 20 73 74 61 74 65 6d 65 6e 74 20   such statement 
1a550 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
1a560 20 0a 2a 2a 20 70 72 6f 67 72 61 6d 2c 20 74 68   .** program, th
1a570 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
1a580 20 72 65 66 6c 65 63 74 73 20 74 68 65 20 6e 75   reflects the nu
1a590 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64  mber of rows mod
1a5a0 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
1a5b0 20 70 72 65 76 69 6f 75 73 20 49 4e 53 45 52 54   previous INSERT
1a5c0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
1a5d0 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  TE statement wit
1a5e0 68 69 6e 20 74 68 65 20 73 61 6d 65 20 74 72 69  hin the same tri
1a5f0 67 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  gger..**.** See 
1a600 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
1a610 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1a620 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
1a630 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
1a640 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
1a650 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
1a660 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
1a670 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
1a680 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
1a690 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
1a6a0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1a6b0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
1a6c0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
1a6d0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
1a6e0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
1a6f0 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
1a700 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1a710 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
1a720 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1a730 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
1a740 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
1a750 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1a760 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
1a770 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
1a780 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20 4d 45  s Modified.** ME
1a790 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1a7a0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
1a7b0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 74  on returns the t
1a7c0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 72  otal number of r
1a7d0 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20 6d 6f  ows inserted, mo
1a7e0 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  dified or.** del
1a7f0 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49 4e 53  eted by all [INS
1a800 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 20 6f  ERT], [UPDATE] o
1a810 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
1a820 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65 64 0a  ments completed.
1a830 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64 61 74  ** since the dat
1a840 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a850 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69 6e 63   was opened, inc
1a860 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65 78 65  luding those exe
1a870 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61 72 74  cuted as.** part
1a880 20 6f 66 20 74 72 69 67 67 65 72 20 70 72 6f 67   of trigger prog
1a890 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69 6e 67  rams. ^Executing
1a8a0 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70 65 20   any other type 
1a8b0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1a8c0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61 66 66  .** does not aff
1a8d0 65 63 74 20 74 68 65 20 76 61 6c 75 65 20 72 65  ect the value re
1a8e0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
1a8f0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1a900 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61 6e 67  )..** .** ^Chang
1a910 65 73 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  es made as part 
1a920 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  of [foreign key 
1a930 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69 6e 63  actions] are inc
1a940 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20  luded in the.** 
1a950 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f 73 65  count, but those
1a960 20 6d 61 64 65 20 61 73 20 70 61 72 74 20 6f 66   made as part of
1a970 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74 72 61   REPLACE constra
1a980 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 61  int resolution a
1a990 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68 61 6e  re.** not. ^Chan
1a9a0 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
1a9b0 61 74 20 61 72 65 20 69 6e 74 65 72 63 65 70 74  at are intercept
1a9c0 65 64 20 62 79 20 49 4e 53 54 45 41 44 20 4f 46  ed by INSTEAD OF
1a9d0 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20 61 72   triggers .** ar
1a9e0 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 0a 2a  e not counted..*
1a9f0 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  * .** See also t
1aa00 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
1aa10 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1aa20 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
1aa30 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
1aa40 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
1aa50 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1aa60 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
1aa70 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1aa80 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
1aa90 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
1aaa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1aab0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
1aac0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1aad0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
1aae0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
1aaf0 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
1ab00 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1ab10 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
1ab20 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1ab30 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
1ab40 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1ab50 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
1ab60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1ab70 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c  F: Interrupt A L
1ab80 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72  ong-Running Quer
1ab90 79 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  y.** METHOD: sql
1aba0 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ite3.**.** ^This
1abb0 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73   function causes
1abc0 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74   any pending dat
1abd0 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20  abase operation 
1abe0 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20  to abort and.** 
1abf0 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61  return at its ea
1ac00 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69  rliest opportuni
1ac10 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65  ty. This routine
1ac20 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a   is typically.**
1ac30 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f   called in respo
1ac40 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63  nse to a user ac
1ac50 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65  tion such as pre
1ac60 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a  ssing "Cancel".*
1ac70 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72  * or Ctrl-C wher
1ac80 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73  e the user wants
1ac90 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70   a long query op
1aca0 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a  eration to halt.
1acb0 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a  ** immediately..
1acc0 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66  **.** ^It is saf
1acd0 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72  e to call this r
1ace0 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68  outine from a th
1acf0 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66  read different f
1ad00 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61  rom the.** threa
1ad10 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e  d that is curren
1ad20 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20  tly running the 
1ad30 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
1ad40 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69  on.  But it.** i
1ad50 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61  s not safe to ca
1ad60 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
1ad70 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65  with a [database
1ad80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
1ad90 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f  t.** is closed o
1ada0 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65  r might close be
1adb0 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  fore sqlite3_int
1adc0 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73  errupt() returns
1add0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53  ..**.** ^If an S
1ade0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  QL operation is 
1adf0 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69  very nearly fini
1ae00 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65  shed at the time
1ae10 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   when.** sqlite3
1ae20 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20  _interrupt() is 
1ae30 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20  called, then it 
1ae40 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61  might not have a
1ae50 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a  n opportunity.**
1ae60 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74   to be interrupt
1ae70 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e  ed and might con
1ae80 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74  tinue to complet
1ae90 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53  ion..**.** ^An S
1aea0 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  QL operation tha
1aeb0 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64  t is interrupted
1aec0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
1aed0 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e  LITE_INTERRUPT].
1aee0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65  .** ^If the inte
1aef0 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72  rrupted SQL oper
1af00 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45  ation is an INSE
1af10 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
1af20 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73  ELETE.** that is
1af30 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69   inside an expli
1af40 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c  cit transaction,
1af50 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65   then the entire
1af60 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20   transaction.** 
1af70 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62  will be rolled b
1af80 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
1af90 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  y..**.** ^The sq
1afa0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1afb0 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66  D) call is in ef
1afc0 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63  fect until all c
1afd0 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
1afe0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1aff0 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ts on [database 
1b000 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f  connection] D co
1b010 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65  mplete.  ^Any ne
1b020 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1b030 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1b040 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1b050 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1b060 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f  () call and befo
1b070 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69  re the .** runni
1b080 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65  ng statements re
1b090 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69  aches zero are i
1b0a0 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66  nterrupted as if
1b0b0 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a   they had been.*
1b0c0 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20  * running prior 
1b0d0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  to the sqlite3_i
1b0e0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e  nterrupt() call.
1b0f0 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65    ^New SQL state
1b100 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1b110 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1b120 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  the running stat
1b130 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63  ement count reac
1b140 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20  hes zero are.** 
1b150 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20  not effected by 
1b160 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1b170 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63  rrupt()..** ^A c
1b180 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
1b190 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74  nterrupt(D) that
1b1a0 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65   occurs when the
1b1b0 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e  re are no runnin
1b1c0 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
1b1d0 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61  nts is a no-op a
1b1e0 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74  nd has no effect
1b1f0 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   on SQL statemen
1b200 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
1b210 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
1b220 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1b230 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e  pt() call return
1b240 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  s..**.** If the 
1b250 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b260 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65  ion closes while
1b270 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72   [sqlite3_interr
1b280 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e  upt()].** is run
1b290 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68  ning then bad th
1b2a0 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  ings will likely
1b2b0 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49   happen..*/.SQLI
1b2c0 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49  TE_API void SQLI
1b2d0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1b2e0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
1b2f0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1b300 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
1b310 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
1b320 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
1b330 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
1b340 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
1b350 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
1b360 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
1b370 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
1b380 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
1b390 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
1b3a0 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
1b3b0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1b3c0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
1b3d0 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
1b3e0 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
1b3f0 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
1b400 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
1b410 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
1b420 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1b430 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
1b440 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
1b450 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
1b460 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1b470 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
1b480 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
1b490 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
1b4a0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
1b4b0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
1b4c0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
1b4d0 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
1b4e0 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
1b4f0 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
1b500 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
1b510 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
1b520 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
1b530 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
1b540 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
1b550 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
1b560 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
1b570 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
1b580 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
1b590 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
1b5a0 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
1b5b0 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
1b5c0 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
1b5d0 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
1b5e0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
1b5f0 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
1b600 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
1b610 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
1b620 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
1b630 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
1b640 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1b650 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
1b660 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
1b670 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
1b680 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1b690 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
1b6a0 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
1b6b0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
1b6c0 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
1b6d0 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
1b6e0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
1b6f0 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
1b700 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
1b710 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
1b720 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
1b730 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
1b740 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
1b750 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
1b760 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
1b770 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
1b780 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1b790 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
1b7a0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
1b7b0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
1b7c0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
1b7d0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1b7e0 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
1b7f0 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
1b800 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
1b810 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
1b820 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b830 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
1b840 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
1b850 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1b860 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
1b870 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
1b880 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
1b890 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1b8a0 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
1b8b0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1b8c0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
1b8d0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
1b8e0 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1b8f0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
1b900 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1b910 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1b920 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
1b930 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1b940 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1b950 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
1b960 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  L sqlite3_comple
1b970 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
1b980 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ql);.SQLITE_API 
1b990 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
1b9a0 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  LL sqlite3_compl
1b9b0 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
1b9c0 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
1b9d0 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
1b9e0 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
1b9f0 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
1ba00 53 59 20 45 72 72 6f 72 73 0a 2a 2a 20 4b 45 59  SY Errors.** KEY
1ba10 57 4f 52 44 53 3a 20 7b 62 75 73 79 2d 68 61 6e  WORDS: {busy-han
1ba20 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 7d 20 7b  dler callback} {
1ba30 62 75 73 79 20 68 61 6e 64 6c 65 72 7d 0a 2a 2a  busy handler}.**
1ba40 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
1ba50 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ba60 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1ba70 28 44 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20  (D,X,P) routine 
1ba80 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
1ba90 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68  function X.** th
1baa0 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  at might be invo
1bab0 6b 65 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ked with argumen
1bac0 74 20 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20  t P whenever.** 
1bad0 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61  an attempt is ma
1bae0 64 65 20 74 6f 20 61 63 63 65 73 73 20 61 20 64  de to access a d
1baf0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 61 73  atabase table as
1bb00 73 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a  sociated with.**
1bb10 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1bb20 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e  ction] D when an
1bb30 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
1bb40 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 74  or process has t
1bb50 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e  he table locked.
1bb60 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1bb70 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69  busy_handler() i
1bb80 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
1bb90 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a   to implement.**
1bba0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74   [sqlite3_busy_t
1bbb0 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50  imeout()] and [P
1bbc0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1bbd0 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ut]..**.** ^If t
1bbe0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1bbf0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
1bc00 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1bc10 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
1bc20 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
1bc30 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
1bc40 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
1bc50 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
1bc60 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
1bc70 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
1bc80 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1bc90 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
1bca0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1bcb0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1bcc0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1bcd0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1bce0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
1bcf0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
1bd00 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
1bd10 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1bd20 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
1bd30 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
1bd40 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
1bd50 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
1bd60 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1bd70 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
1bd80 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
1bd90 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
1bda0 70 72 65 76 69 6f 75 73 6c 79 20 66 6f 72 20 74  previously for t
1bdb0 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e 67 20  he same locking 
1bdc0 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a  event.  ^If the.
1bdd0 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  ** busy callback
1bde0 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e   returns 0, then
1bdf0 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61   no additional a
1be00 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65  ttempts are made
1be10 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68   to.** access th
1be20 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b  e database and [
1be30 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 69 73 20  SQLITE_BUSY] is 
1be40 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74 6f 20 74  returned.** to t
1be50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 0a  he application..
1be60 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  ** ^If the callb
1be70 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
1be80 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68  zero, then anoth
1be90 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73  er attempt.** is
1bea0 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
1beb0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
1bec0 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
1bed0 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
1bee0 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
1bef0 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
1bf00 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
1bf10 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
1bf20 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
1bf30 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
1bf40 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
1bf50 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
1bf60 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
1bf70 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
1bf80 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
1bf90 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
1bfa0 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
1bfb0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
1bfc0 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70  SY].** to the ap
1bfd0 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73 74 65 61  plication instea
1bfe0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
1bff0 65 20 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c  e .** busy handl
1c000 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
1c010 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
1c020 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
1c030 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
1c040 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
1c050 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
1c060 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
1c070 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
1c080 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
1c090 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
1c0a0 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
1c0b0 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
1c0c0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
1c0d0 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
1c0e0 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
1c0f0 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
1c100 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
1c110 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1c120 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
1c130 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1c140 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
1c150 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
1c160 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
1c170 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
1c180 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
1c190 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
1c1a0 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
1c1b0 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
1c1c0 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
1c1d0 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
1c1e0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
1c1f0 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
1c200 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
1c210 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
1c220 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
1c230 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
1c240 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
1c250 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
1c260 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1c270 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
1c280 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1c290 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
1c2a0 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
1c2b0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1c2c0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1c2d0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
1c2e0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
1c2f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c300 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
1c310 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
1c320 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
1c330 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
1c340 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
1c350 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
1c360 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1c370 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65 76 61 6c  ut()].** or eval
1c380 75 61 74 69 6e 67 20 5b 50 52 41 47 4d 41 20 62  uating [PRAGMA b
1c390 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e 5d 20 77  usy_timeout=N] w
1c3a0 69 6c 6c 20 63 68 61 6e 67 65 20 74 68 65 0a 2a  ill change the.*
1c3b0 2a 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 61  * busy handler a
1c3c0 6e 64 20 74 68 75 73 20 63 6c 65 61 72 20 61 6e  nd thus clear an
1c3d0 79 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  y previously set
1c3e0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1c3f0 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
1c400 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
1c410 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
1c420 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
1c430 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1c440 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1c450 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1c460 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e 20 6f 74   handler.  In ot
1c470 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a 20 74 68  her words,.** th
1c480 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  e busy handler i
1c490 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e  s not reentrant.
1c4a0 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f    Any such actio
1c4b0 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20  ns.** result in 
1c4c0 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
1c4d0 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73  or..** .** A bus
1c4e0 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e  y handler must n
1c4f0 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74  ot close the dat
1c500 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c510 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64  .** or [prepared
1c520 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
1c530 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73   invoked the bus
1c540 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51  y handler..*/.SQ
1c550 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
1c560 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
1c570 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1c580 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
1c590 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
1c5a0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1c5b0 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
1c5c0 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54  y Timeout.** MET
1c5d0 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1c5e0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1c5f0 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33   sets a [sqlite3
1c600 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20  _busy_handler | 
1c610 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68  busy handler] th
1c620 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72  at sleeps.** for
1c630 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f   a specified amo
1c640 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e  unt of time when
1c650 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b   a table is lock
1c660 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  ed.  ^The handle
1c670 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20  r.** will sleep 
1c680 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75  multiple times u
1c690 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d  ntil at least "m
1c6a0 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
1c6b0 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68  of sleeping.** h
1c6c0 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e  ave accumulated.
1c6d0 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73    ^After at leas
1c6e0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1c6f0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c  nds of sleeping,
1c700 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20  .** the handler 
1c710 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20  returns 0 which 
1c720 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f  causes [sqlite3_
1c730 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72  step()] to retur
1c740 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53  n.** [SQLITE_BUS
1c750 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  Y]..**.** ^Calli
1c760 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
1c770 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
1c780 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
1c790 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
1c7a0 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
1c7b0 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
1c7c0 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
1c7d0 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
1c7e0 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
1c7f0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
1c800 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c810 74 69 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76  tion] at any giv
1c820 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
1c830 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
1c840 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
1c850 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
1c860 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1c870 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
1c880 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
1c890 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
1c8a0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
1c8b0 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a  s cleared.)^.**.
1c8c0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50  ** See also:  [P
1c8d0 52 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f  RAGMA busy_timeo
1c8e0 75 74 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ut].*/.SQLITE_AP
1c8f0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
1c900 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 75 73  CALL sqlite3_bus
1c910 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
1c920 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
1c930 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1c940 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
1c950 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
1c960 75 65 72 69 65 73 0a 2a 2a 20 4d 45 54 48 4f 44  ueries.** METHOD
1c970 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
1c980 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79  This is a legacy
1c990 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
1c9a0 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72  is preserved for
1c9b0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1c9c0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65  tibility..** Use
1c9d0 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
1c9e0 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d  ce is not recomm
1c9f0 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66  ended..**.** Def
1ca00 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65  inition: A <b>re
1ca10 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69  sult table</b> i
1ca20 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74  s memory data st
1ca30 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20  ructure created 
1ca40 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  by the.** [sqlit
1ca50 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1ca60 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65  interface.  A re
1ca70 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72  sult table recor
1ca80 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65  ds the.** comple
1ca90 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  te query results
1caa0 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72   from one or mor
1cab0 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a  e queries..**.**
1cac0 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65   The table conce
1cad0 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75  ptually has a nu
1cae0 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64  mber of rows and
1caf0 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a   columns.  But.*
1cb00 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20  * these numbers 
1cb10 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20  are not part of 
1cb20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1cb30 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a   itself.  These.
1cb40 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f  ** numbers are o
1cb50 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65  btained separate
1cb60 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68  ly.  Let N be th
1cb70 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  e number of rows
1cb80 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65  .** and M be the
1cb90 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
1cba0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  ns..**.** A resu
1cbb0 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61  lt table is an a
1cbc0 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
1cbd0 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
1cbe0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
1cbf0 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  s..** There are 
1cc00 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73  (N+1)*M elements
1cc10 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20   in the array.  
1cc20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e  The first M poin
1cc30 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f  ters point.** to
1cc40 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1cc50 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63   strings that  c
1cc60 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  ontain the names
1cc70 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e   of the columns.
1cc80 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e  .** The remainin
1cc90 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f  g entries all po
1cca0 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73  int to query res
1ccb0 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75  ults.  NULL valu
1ccc0 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20  es result.** in 
1ccd0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20  NULL pointers.  
1cce0 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73  All other values
1ccf0 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54   are in their UT
1cd00 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  F-8 zero-termina
1cd10 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65  ted.** string re
1cd20 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20  presentation as 
1cd30 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1cd40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
1cd50 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  ()]..**.** A res
1cd60 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20  ult table might 
1cd70 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f  consist of one o
1cd80 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c  r more memory al
1cd90 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74  locations..** It
1cda0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
1cdb0 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61  pass a result ta
1cdc0 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ble directly to 
1cdd0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1cde0 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  ..** A result ta
1cdf0 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65  ble should be de
1ce00 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20  allocated using 
1ce10 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
1ce20 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ble()]..**.** ^(
1ce30 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  As an example of
1ce40 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1ce50 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73  e format, suppos
1ce60 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74  e a query result
1ce70 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  .** is as follow
1ce80 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1ce90 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1cea0 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20       Name       
1ceb0 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20   | Age.**       
1cec0 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d   ---------------
1ced0 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20  --------.**     
1cee0 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c     Alice       |
1cef0 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f   43.**        Bo
1cf00 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a  b         | 28.*
1cf10 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20  *        Cindy  
1cf20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70       | 21.** </p
1cf30 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1cf40 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  .**.** There are
1cf50 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d   two column (M==
1cf60 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77  2) and three row
1cf70 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20  s (N==3).  Thus 
1cf80 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61  the.** result ta
1cf90 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65  ble has 8 entrie
1cfa0 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20  s.  Suppose the 
1cfb0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1cfc0 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20  stored.** in an 
1cfd0 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65  array names azRe
1cfe0 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65  sult.  Then azRe
1cff0 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20  sult holds this 
1d000 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c  content:.**.** <
1d010 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1d020 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1d030 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61  ult&#91;0] = "Na
1d040 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  me";.**        a
1d050 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d  zResult&#91;1] =
1d060 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20   "Age";.**      
1d070 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32    azResult&#91;2
1d080 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20  ] = "Alice";.** 
1d090 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1d0a0 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a  #91;3] = "43";.*
1d0b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1d0c0 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22  t&#91;4] = "Bob"
1d0d0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1d0e0 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32  sult&#91;5] = "2
1d0f0 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  8";.**        az
1d100 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20  Result&#91;6] = 
1d110 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20  "Cindy";.**     
1d120 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1d130 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f  7] = "21";.** </
1d140 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1d150 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  >)^.**.** ^The s
1d160 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d170 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c  () function eval
1d180 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72  uates one or mor
1d190 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73  e.** semicolon-s
1d1a0 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61  eparated SQL sta
1d1b0 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a  tements in the z
1d1c0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
1d1d0 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  TF-8.** string o
1d1e0 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65  f its 2nd parame
1d1f0 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
1d200 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74  a result table t
1d210 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72  o the.** pointer
1d220 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72   given in its 3r
1d230 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
1d240 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70  ** After the app
1d250 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
1d260 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72  ished with the r
1d270 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74  esult from sqlit
1d280 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a  e3_get_table(),.
1d290 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20  ** it must pass 
1d2a0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1d2b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
1d2c0 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29  te3_free_table()
1d2d0 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
1d2e0 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
1d2f0 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c  ry that was mall
1d300 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f  oced.  Because o
1d310 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a  f the way the.**
1d320 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1d330 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68  ()] happens with
1d340 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  in sqlite3_get_t
1d350 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c  able(), the call
1d360 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
1d370 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20  must not try to 
1d380 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72  call [sqlite3_fr
1d390 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20  ee()] directly. 
1d3a0 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65   Only.** [sqlite
1d3b0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20  3_free_table()] 
1d3c0 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61  is able to relea
1d3d0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
1d3e0 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c  operly and safel
1d3f0 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  y..**.** The sql
1d400 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1d410 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d   interface is im
1d420 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77  plemented as a w
1d430 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
1d440 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1d450 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ].  The sqlite3_
1d460 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74  get_table() rout
1d470 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  ine does not hav
1d480 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61  e access.** to a
1d490 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ny internal data
1d4a0 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53   structures of S
1d4b0 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20  QLite.  It uses 
1d4c0 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a  only the public.
1d4d0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66  ** interface def
1d4e0 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61  ined here.  As a
1d4f0 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72   consequence, er
1d500 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20  rors that occur 
1d510 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65  in the.** wrappe
1d520 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20  r layer outside 
1d530 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  of the internal 
1d540 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1d550 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a   call are not.**
1d560 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75   reflected in su
1d570 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
1d580 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
1d590 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  de()] or.** [sql
1d5a0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
1d5b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1d5c0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
1d5d0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1d5e0 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
1d5f0 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
1d600 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
1d610 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1d620 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
1d630 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
1d640 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
1d650 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
1d660 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
1d670 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
1d680 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
1d690 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1d6a0 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
1d6b0 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
1d6c0 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
1d6d0 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1d6e0 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
1d6f0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
1d700 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
1d710 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
1d720 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
1d730 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
1d740 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
1d750 41 4c 4c 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ALL sqlite3_free
1d760 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1d770 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1d780 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1d790 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1d7a0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1d7b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1d7c0 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1d7d0 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1d7e0 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1d7f0 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1d800 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1d810 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20  brary..** These 
1d820 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74  routines underst
1d830 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20  and most of the 
1d840 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61  common K&R forma
1d850 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a  tting options,.*
1d860 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69  * plus some addi
1d870 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64  tional non-stand
1d880 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74  ard formats, det
1d890 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20  ailed below..** 
1d8a0 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f  Note that some o
1d8b0 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75  f the more obscu
1d8c0 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  re formatting op
1d8d0 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e  tions from recen
1d8e0 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73  t.** C-library s
1d8f0 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69  tandards are omi
1d900 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69  tted from this i
1d910 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
1d920 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d930 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1d940 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1d950 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1d960 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1d970 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1d980 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1d990 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1d9a0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1d9b0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1d9c0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1d9d0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1d9e0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1d9f0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1da00 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1da10 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1da20 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1da30 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1da40 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1da50 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1da60 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1da70 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1da80 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1da90 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1daa0 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1dab0 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1dac0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1dad0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1dae0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1daf0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1db00 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1db10 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1db20 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1db30 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1db40 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1db50 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1db60 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1db70 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1db80 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1db90 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1dba0 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1dbb0 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1dbc0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1dbd0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1dbe0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1dbf0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1dc00 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1dc10 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1dc20 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1dc30 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1dc40 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1dc50 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1dc60 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1dc70 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1dc80 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1dc90 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1dca0 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1dcb0 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1dcc0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1dcd0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1dce0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1dcf0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1dd00 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1dd10 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1dd20 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1dd30 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1dd40 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1dd50 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1dd60 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1dd70 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1dd80 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1dd90 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1dda0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1ddb0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1ddc0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1ddd0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1dde0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1ddf0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1de00 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1de10 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1de20 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1de30 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1de40 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1de50 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1de60 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1de70 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1de80 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1de90 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1dea0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1deb0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1dec0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1ded0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1dee0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1def0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1df00 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1df10 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1df20 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1df30 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1df40 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1df50 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1df60 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1df70 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1df80 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1df90 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1dfa0 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1dfb0 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1dfc0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1dfd0 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70  "%w" and "%z" op
1dfe0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1dff0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1e000 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1e010 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1e020 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1e030 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1e040 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1e050 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1e060 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1e070 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1e080 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1e090 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1e0a0 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1e0b0 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1e0c0 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1e0d0 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1e0e0 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1e0f0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1e100 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1e110 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1e120 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1e130 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1e140 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1e150 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1e160 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1e170 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e180 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1e190 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1e1a0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1e1b0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1e1c0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1e1d0 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1e1e0 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1e1f0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1e200 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1e210 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e220 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1e230 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1e240 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1e250 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1e260 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1e270 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1e280 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1e290 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1e2a0 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1e2b0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e2c0 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1e2d0 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1e2e0 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1e2f0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1e300 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1e310 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1e320 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1e330 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1e340 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1e350 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1e360 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1e370 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1e380 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1e390 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1e3a0 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1e3b0 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1e3c0 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1e3d0 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1e3e0 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1e3f0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1e400 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1e410 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1e420 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1e430 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1e440 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1e450 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1e460 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1e470 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1e480 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1e490 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1e4a0 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1e4b0 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1e4c0 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1e4d0 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1e4e0 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1e4f0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1e500 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1e510 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1e520 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1e530 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1e540 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1e550 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1e560 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1e570 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1e580 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1e590 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1e5a0 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1e5b0 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1e5c0 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1e5d0 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1e5e0 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1e5f0 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1e600 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1e610 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1e620 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1e630 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1e640 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1e650 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1e660 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1e670 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1e680 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1e690 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1e6a0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1e6b0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1e6c0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1e6d0 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1e6e0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1e6f0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1e700 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1e710 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1e720 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1e730 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1e740 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1e750 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72  * ^(The "%w" for
1e760 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1e770 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65  s like "%q" exce
1e780 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63  pt that it expec
1e790 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74  ts to.** be cont
1e7a0 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75  ained within dou
1e7b0 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65  ble-quotes inste
1e7c0 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f  ad of single quo
1e7d0 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65  tes, and it.** e
1e7e0 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c  scapes the doubl
1e7f0 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  e-quote characte
1e800 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1e810 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a   single-quote.**
1e820 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54   character.)^  T
1e830 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1e840 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74  ng option is int
1e850 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79  ended for safely
1e860 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61   inserting.** ta
1e870 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e  ble and column n
1e880 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73  ames into a cons
1e890 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74  tructed SQL stat
1e8a0 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ement..**.** ^(T
1e8b0 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1e8c0 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1e8d0 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1e8e0 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1e8f0 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1e900 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1e910 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1e920 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1e930 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1e940 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1e950 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1e960 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54  ring.)^.*/.SQLIT
1e970 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49  E_API char *SQLI
1e980 54 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33  TE_CDECL sqlite3
1e990 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
1e9a0 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54  har*,...);.SQLIT
1e9b0 45 5f 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49  E_API char *SQLI
1e9c0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1e9d0 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73  e3_vmprintf(cons
1e9e0 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1e9f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1ea00 61 72 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c  ar *SQLITE_CDECL
1ea10 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1ea20 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1ea30 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53  t char*, ...);.S
1ea40 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1ea50 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
1ea60 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66  qlite3_vsnprintf
1ea70 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74  (int,char*,const
1ea80 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1ea90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1eaa0 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1eab0 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a  tion Subsystem.*
1eac0 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20  *.** The SQLite 
1ead0 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20  core uses these 
1eae0 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66  three routines f
1eaf0 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77  or all of its ow
1eb00 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65  n.** internal me
1eb10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1eb20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e  needs. "Core" in
1eb30 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65   the previous se
1eb40 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e  ntence.** does n
1eb50 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61  ot include opera
1eb60 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63  ting-system spec
1eb70 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65  ific VFS impleme
1eb80 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a  ntation.  The.**
1eb90 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65   Windows VFS use
1eba0 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28  s native malloc(
1ebb0 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72  ) and free() for
1ebc0 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73   some operations
1ebd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1ebe0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f  ite3_malloc() ro
1ebf0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
1ec00 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f  pointer to a blo
1ec10 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  ck.** of memory 
1ec20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1ec30 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72   in length, wher
1ec40 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d  e N is the param
1ec50 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  eter..** ^If sql
1ec60 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1ec70 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69   unable to obtai
1ec80 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65  n sufficient fre
1ec90 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20  e.** memory, it 
1eca0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1ecb0 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65  ointer.  ^If the
1ecc0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a   parameter N to.
1ecd0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1ece0 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e  c() is zero or n
1ecf0 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c  egative then sql
1ed00 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65  ite3_malloc() re
1ed10 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  turns.** a NULL 
1ed20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
1ed30 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  The sqlite3_mall
1ed40 6f 63 36 34 28 4e 29 20 72 6f 75 74 69 6e 65 20  oc64(N) routine 
1ed50 77 6f 72 6b 73 20 6a 75 73 74 20 6c 69 6b 65 0a  works just like.
1ed60 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1ed70 63 28 4e 29 20 65 78 63 65 70 74 20 74 68 61 74  c(N) except that
1ed80 20 4e 20 69 73 20 61 6e 20 75 6e 73 69 67 6e 65   N is an unsigne
1ed90 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  d 64-bit integer
1eda0 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61   instead.** of a
1edb0 20 73 69 67 6e 65 64 20 33 32 2d 62 69 74 20 69   signed 32-bit i
1edc0 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  nteger..**.** ^C
1edd0 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
1ede0 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
1edf0 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
1ee00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1ee10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1ee20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1ee30 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
1ee40 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
1ee50 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
1ee60 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
1ee70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
1ee80 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
1ee90 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
1eea0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
1eeb0 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
1eec0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
1eed0 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1eee0 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
1eef0 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
1ef00 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
1ef10 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
1ef20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
1ef30 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
1ef40 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
1ef50 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
1ef60 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
1ef70 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
1ef80 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1ef90 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
1efa0 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
1efb0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1efc0 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
1efd0 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
1efe0 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
1eff0 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
1f000 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
1f010 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
1f020 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
1f030 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
1f040 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1f050 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1f060 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1f070 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1f080 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
1f090 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
1f0a0 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
1f0b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 58 20 74 6f   allocation X to
1f0c0 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
1f0d0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
1f0e0 20 58 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   X parameter to 
1f0f0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f100 58 2c 4e 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  X,N).** is a NUL
1f110 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69  L pointer then i
1f120 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69  ts behavior is i
1f130 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c  dentical to call
1f140 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ing.** sqlite3_m
1f150 61 6c 6c 6f 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66  alloc(N)..** ^If
1f160 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
1f170 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1f180 6c 6f 63 28 58 2c 4e 29 20 69 73 20 7a 65 72 6f  loc(X,N) is zero
1f190 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20   or.** negative 
1f1a0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1f1b0 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65  r is exactly the
1f1c0 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67   same as calling
1f1d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65  .** sqlite3_free
1f1e0 28 58 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  (X)..** ^sqlite3
1f1f0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65  _realloc(X,N) re
1f200 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1f210 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
1f220 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
1f230 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1f240 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
1f250 20 69 6e 73 75 66 66 69 63 69 65 6e 74 20 6d 65   insufficient me
1f260 6d 6f 72 79 20 69 73 20 61 76 61 69 6c 61 62 6c  mory is availabl
1f270 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74  e..** ^If M is t
1f280 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
1f290 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
1f2a0 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
1f2b0 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
1f2c0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1f2d0 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
1f2e0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
1f2f0 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
1f300 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
1f310 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 61 6e 64 20  ealloc(X,N) and 
1f320 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1f330 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
1f340 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
1f350 61 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72  alloc(X,N) retur
1f360 6e 73 20 4e 55 4c 4c 20 61 6e 64 20 4e 20 69 73  ns NULL and N is
1f370 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
1f380 74 68 65 0a 2a 2a 20 70 72 69 6f 72 20 61 6c 6c  the.** prior all
1f390 6f 63 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 66  ocation is not f
1f3a0 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  reed..**.** ^The
1f3b0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1f3c0 36 34 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  64(X,N) interfac
1f3d0 65 73 20 77 6f 72 6b 73 20 74 68 65 20 73 61 6d  es works the sam
1f3e0 65 20 61 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  e as.** sqlite3_
1f3f0 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 65 78 63  realloc(X,N) exc
1f400 65 70 74 20 74 68 61 74 20 4e 20 69 73 20 61 20  ept that N is a 
1f410 36 34 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20  64-bit unsigned 
1f420 69 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a  integer instead.
1f430 2a 2a 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73  ** of a 32-bit s
1f440 69 67 6e 65 64 20 69 6e 74 65 67 65 72 2e 0a 2a  igned integer..*
1f450 2a 0a 2a 2a 20 5e 49 66 20 58 20 69 73 20 61 20  *.** ^If X is a 
1f460 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f470 6e 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  n previously obt
1f480 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
1f490 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20  e3_malloc(),.** 
1f4a0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1f4b0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  (), sqlite3_real
1f4c0 6c 6f 63 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  loc(), or sqlite
1f4d0 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29 2c 20 74  3_realloc64(), t
1f4e0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  hen.** sqlite3_m
1f4f0 73 69 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20  size(X) returns 
1f500 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 61 74  the size of that
1f510 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1f520 6f 6e 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2a 20  on in bytes..** 
1f530 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72  ^The value retur
1f540 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1f550 73 69 7a 65 28 58 29 20 6d 69 67 68 74 20 62 65  size(X) might be
1f560 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
1f570 20 6e 75 6d 62 65 72 0a 2a 2a 20 6f 66 20 62 79   number.** of by
1f580 74 65 73 20 72 65 71 75 65 73 74 65 64 20 77 68  tes requested wh
1f590 65 6e 20 58 20 77 61 73 20 61 6c 6c 6f 63 61 74  en X was allocat
1f5a0 65 64 2e 20 20 5e 49 66 20 58 20 69 73 20 61 20  ed.  ^If X is a 
1f5b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1f5c0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69  n.** sqlite3_msi
1f5d0 7a 65 28 58 29 20 72 65 74 75 72 6e 73 20 7a 65  ze(X) returns ze
1f5e0 72 6f 2e 20 20 49 66 20 58 20 70 6f 69 6e 74 73  ro.  If X points
1f5f0 20 74 6f 20 73 6f 6d 65 74 68 69 6e 67 20 74 68   to something th
1f600 61 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65  at is not.** the
1f610 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 6d 65   beginning of me
1f620 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  mory allocation,
1f630 20 6f 72 20 69 66 20 69 74 20 70 6f 69 6e 74 73   or if it points
1f640 20 74 6f 20 61 20 66 6f 72 6d 65 72 6c 79 0a 2a   to a formerly.*
1f650 2a 20 76 61 6c 69 64 20 6d 65 6d 6f 72 79 20 61  * valid memory a
1f660 6c 6c 6f 63 61 74 69 6f 6e 20 74 68 61 74 20 68  llocation that h
1f670 61 73 20 6e 6f 77 20 62 65 65 6e 20 66 72 65 65  as now been free
1f680 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  d, then the beha
1f690 76 69 6f 72 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  vior.** of sqlit
1f6a0 65 33 5f 6d 73 69 7a 65 28 58 29 20 69 73 20 75  e3_msize(X) is u
1f6b0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 6f 73  ndefined and pos
1f6c0 73 69 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  sibly harmful..*
1f6d0 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1f6e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1f6f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73  ite3_malloc(), s
1f700 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1f710 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ,.** sqlite3_mal
1f720 6c 6f 63 36 34 28 29 2c 20 61 6e 64 20 73 71 6c  loc64(), and sql
1f730 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 29  ite3_realloc64()
1f740 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c  .** is always al
1f750 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73  igned to at leas
1f760 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e  t an 8 byte boun
1f770 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a  dary, or to a.**
1f780 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   4 byte boundary
1f790 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1f7a0 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d  4_BYTE_ALIGNED_M
1f7b0 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74  ALLOC] compile-t
1f7c0 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73  ime.** option is
1f7d0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20   used..**.** In 
1f7e0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1f7f0 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20  .5.0 and 3.5.1, 
1f800 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20  it was possible 
1f810 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65  to define.** the
1f820 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d   SQLITE_OMIT_MEM
1f830 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77  ORY_ALLOCATION w
1f840 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65  hich would cause
1f850 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a   the built-in.**
1f860 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1f870 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
1f880 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e  s to be omitted.
1f890 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74    That capabilit
1f8a0 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  y.** is no longe
1f8b0 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c  r provided.  Onl
1f8c0 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  y built-in memor
1f8d0 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e  y allocators can
1f8e0 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   be used..**.** 
1f8f0 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20  Prior to SQLite 
1f900 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20  version 3.7.10, 
1f910 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69  the Windows OS i
1f920 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63  nterface layer c
1f930 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73  alled.** the sys
1f940 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  tem malloc() and
1f950 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79   free() directly
1f960 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67   when converting
1f970 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65  .** filenames be
1f980 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20  tween the UTF-8 
1f990 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79  encoding used by
1f9a0 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77   SQLite.** and w
1f9b0 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65  hatever filename
1f9c0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
1f9d0 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75  d by the particu
1f9e0 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69  lar Windows.** i
1f9f0 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65  nstallation.  Me
1fa00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1fa10 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65  errors were dete
1fa20 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
1fa30 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20  y were reported 
1fa40 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f  back as [SQLITE_
1fa50 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20  CANTOPEN] or.** 
1fa60 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72  [SQLITE_IOERR] r
1fa70 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  ather than [SQLI
1fa80 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a  TE_NOMEM]..**.**
1fa90 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67   The pointer arg
1faa0 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74  uments to [sqlit
1fab0 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b  e3_free()] and [
1fac0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1fad0 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69  )].** must be ei
1fae0 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73  ther NULL or els
1faf0 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69  e pointers obtai
1fb00 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72  ned from a prior
1fb10 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  .** invocation o
1fb20 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1fb30 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  c()] or [sqlite3
1fb40 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74  _realloc()] that
1fb50 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74   have.** not yet
1fb60 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a   been released..
1fb70 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
1fb80 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72  ation must not r
1fb90 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79  ead or write any
1fba0 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c   part of.** a bl
1fbb0 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66  ock of memory af
1fbc0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
1fbd0 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a  released using.*
1fbe0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
1fbf0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
1fc00 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51  ealloc()]..*/.SQ
1fc10 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53  LITE_API void *S
1fc20 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
1fc30 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
1fc40 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1fc50 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
1fc60 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  LL sqlite3_mallo
1fc70 63 36 34 28 73 71 6c 69 74 65 33 5f 75 69 6e 74  c64(sqlite3_uint
1fc80 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
1fc90 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
1fca0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 65 61  CALL sqlite3_rea
1fcb0 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1fcc0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1fcd0 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
1fce0 4c 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  L sqlite3_reallo
1fcf0 63 36 34 28 76 6f 69 64 2a 2c 20 73 71 6c 69 74  c64(void*, sqlit
1fd00 65 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49  e3_uint64);.SQLI
1fd10 54 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49  TE_API void SQLI
1fd20 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1fd30 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a  e3_free(void*);.
1fd40 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1fd50 65 33 5f 75 69 6e 74 36 34 20 53 51 4c 49 54 45  e3_uint64 SQLITE
1fd60 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1fd70 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
1fd80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1fd90 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1fda0 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1fdb0 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1fdc0 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1fdd0 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1fde0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1fdf0 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1fe00 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1fe10 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1fe20 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1fe30 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1fe40 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1fe50 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1fe60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1fe70 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1fe80 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1fe90 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1fea0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1feb0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1fec0 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1fed0 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1fee0 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1fef0 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1ff00 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1ff10 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1ff20 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1ff30 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1ff40 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1ff50 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1ff60 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1ff70 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1ff80 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1ff90 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1ffa0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1ffb0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1ffc0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1ffd0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1ffe0 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1fff0 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
20000 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
20010 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
20020 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
20030 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
20040 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
20050 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
20060 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
20070 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
20080 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
20090 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
200a0 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
200b0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
200c0 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
200d0 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
200e0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
200f0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
20100 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
20110 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
20120 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
20130 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
20140 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
20150 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
20160 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
20170 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
20180 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
20190 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
201a0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
201b0 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54   reset..*/.SQLIT
201c0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
201d0 74 36 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41  t64 SQLITE_STDCA
201e0 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  LL sqlite3_memor
201f0 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51  y_used(void);.SQ
20200 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
20210 5f 69 6e 74 36 34 20 53 51 4c 49 54 45 5f 53 54  _int64 SQLITE_ST
20220 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 65  DCALL sqlite3_me
20230 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69  mory_highwater(i
20240 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a  nt resetFlag);..
20250 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
20260 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75  Pseudo-Random Nu
20270 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a  mber Generator.*
20280 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74  *.** SQLite cont
20290 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c  ains a high-qual
202a0 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  ity pseudo-rando
202b0 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74  m number generat
202c0 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74  or (PRNG) used t
202d0 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64  o.** select rand
202e0 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49  om [ROWID | ROWI
202f0 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69  Ds] when inserti
20300 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69  ng new records i
20310 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74  nto a table that
20320 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73  .** already uses
20330 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73   the largest pos
20340 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20  sible [ROWID].  
20350 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f  The PRNG is also
20360 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65   used for.** the
20370 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d   build-in random
20380 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f  () and randomblo
20390 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  b() SQL function
203a0 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61  s.  This interfa
203b0 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70  ce allows.** app
203c0 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63  lications to acc
203d0 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e  ess the same PRN
203e0 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70  G for other purp
203f0 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63  oses..**.** ^A c
20400 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74  all to this rout
20410 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74  ine stores N byt
20420 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
20430 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a   into buffer P..
20440 2a 2a 20 5e 54 68 65 20 50 20 70 61 72 61 6d 65  ** ^The P parame
20450 74 65 72 20 63 61 6e 20 62 65 20 61 20 4e 55 4c  ter can be a NUL
20460 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
20470 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e   ^If this routin
20480 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70  e has not been p
20490 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64  reviously called
204a0 20 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69   or if the previ
204b0 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20  ous.** call had 
204c0 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20  N less than one 
204d0 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
204e0 72 20 66 6f 72 20 50 2c 20 74 68 65 6e 20 74 68  r for P, then th
204f0 65 20 50 52 4e 47 20 69 73 0a 2a 2a 20 73 65 65  e PRNG is.** see
20500 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
20510 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ness obtained fr
20520 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65  om the xRandomne
20530 73 73 20 6d 65 74 68 6f 64 20 6f 66 0a 2a 2a 20  ss method of.** 
20540 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
20550 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
20560 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65  ..** ^If the pre
20570 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
20580 69 73 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61  is routine had a
20590 6e 20 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65  n N of 1 or more
205a0 20 61 6e 64 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55   and a.** non-NU
205b0 4c 4c 20 50 20 74 68 65 6e 20 74 68 65 20 70 73  LL P then the ps
205c0 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
205d0 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
205e0 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
205f0 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
20600 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
20610 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
20620 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53  .** method..*/.S
20630 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 53  QLITE_API void S
20640 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
20650 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73  lite3_randomness
20660 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29  (int N, void *P)
20670 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20680 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20  F: Compile-Time 
20690 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61  Authorization Ca
206a0 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f  llbacks.** METHO
206b0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
206c0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
206d0 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
206e0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
206f0 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
20700 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
20710 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
20720 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
20730 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
20740 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
20750 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
20760 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
20770 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
20780 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
20790 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
207a0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
207b0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
207c0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
207d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
207e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
207f0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
20800 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
20810 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
20820 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
20830 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
20840 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
20850 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
20860 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
20870 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20880 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
20890 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
208a0 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
208b0 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
208c0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
208d0 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
208e0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
208f0 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
20900 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
20910 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
20920 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
20930 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
20940 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
20950 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
20960 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
20970 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
20980 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
20990 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
209a0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
209b0 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
209c0 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
209d0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
209e0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
209f0 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
20a00 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
20a10 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
20a20 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
20a30 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
20a40 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
20a50 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
20a60 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
20a70 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
20a80 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
20a90 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
20aa0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
20ab0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
20ac0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
20ad0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
20ae0 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
20af0 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
20b00 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
20b10 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
20b20 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
20b30 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
20b40 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20b50 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
20b60 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
20b70 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
20b80 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
20b90 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
20ba0 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
20bb0 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
20bc0 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
20bd0 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
20be0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
20bf0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20c00 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
20c10 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
20c20 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
20c30 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
20c40 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
20c50 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
20c60 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
20c70 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
20c80 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
20c90 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
20ca0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
20cb0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
20cc0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
20cd0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
20ce0 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
20cf0 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
20d00 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
20d10 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
20d20 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
20d30 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
20d40 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
20d50 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
20d60 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
20d70 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
20d80 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
20d90 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
20da0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
20db0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
20dc0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
20dd0 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
20de0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
20df0 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
20e00 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
20e10 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
20e20 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
20e30 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
20e40 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
20e50 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
20e60 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
20e70 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
20e80 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
20e90 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
20ea0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
20eb0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
20ec0 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
20ed0 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
20ee0 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
20ef0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
20f00 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
20f10 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
20f20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
20f30 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
20f40 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
20f50 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
20f60 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
20f70 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
20f80 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
20f90 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
20fa0 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
20fb0 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
20fc0 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
20fd0 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
20fe0 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
20ff0 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
21000 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
21010 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
21020 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
21030 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
21040 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
21050 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
21060 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
21070 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
21080 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
21090 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
210a0 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
210b0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
210c0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
210d0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
210e0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
210f0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
21100 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
21110 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
21120 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
21130 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
21140 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
21150 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
21160 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
21170 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
21180 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
21190 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
211a0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
211b0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
211c0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
211d0 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
211e0 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
211f0 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
21200 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
21210 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
21220 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
21230 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
21240 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
21250 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
21260 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
21270 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
21280 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
21290 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
212a0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
212b0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
212c0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
212d0 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
212e0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
212f0 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
21300 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
21310 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
21320 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
21330 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
21340 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
21350 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
21360 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
21370 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
21380 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
21390 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
213a0 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
213b0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
213c0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
213d0 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
213e0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
213f0 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
21400 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
21410 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
21420 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
21430 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
21440 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
21450 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
21460 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21470 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
21480 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
21490 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
214a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
214b0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
214c0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
214d0 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
214e0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
214f0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
21500 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21510 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
21520 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
21530 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
21540 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
21550 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
21560 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
21570 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
21580 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
21590 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
215a0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
215b0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
215c0 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
215d0 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
215e0 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
215f0 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
21600 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
21610 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
21620 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
21630 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
21640 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
21650 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
21660 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
21670 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
21680 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
21690 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
216a0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
216b0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
216c0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
216d0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
216e0 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
216f0 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
21700 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
21710 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
21720 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
21730 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
21740 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
21750 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
21760 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
21770 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
21780 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
21790 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
217a0 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
217b0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
217c0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
217d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
217e0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
217f0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
21800 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
21810 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
21820 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
21830 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
21840 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
21850 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
21860 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
21870 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
21880 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
21890 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
218a0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
218b0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
218c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
218d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
218e0 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
218f0 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
21900 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
21910 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
21920 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
21930 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
21940 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
21950 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
21960 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
21970 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21980 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
21990 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
219a0 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
219b0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
219c0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
219d0 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
219e0 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
219f0 61 20 5b 63 6f 6e 66 6c 69 63 74 20 72 65 73 6f  a [conflict reso
21a00 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d 0a 2a 2a 20  lution mode].** 
21a10 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 74 68  returned from th
21a20 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
21a30 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
21a40 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
21a50 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
21a60 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
21a70 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
21a80 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
21a90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21aa0 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
21ab0 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
21ac0 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
21ad0 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
21ae0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
21af0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
21b00 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
21b10 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
21b20 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
21b30 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
21b40 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
21b50 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
21b60 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
21b70 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
21b80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
21b90 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
21ba0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
21bb0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
21bc0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
21bd0 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
21be0 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
21bf0 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
21c00 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
21c10 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
21c20 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
21c30 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
21c40 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
21c50 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
21c60 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
21c70 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
21c80 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
21c90 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
21ca0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
21cb0 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
21cc0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
21cd0 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
21ce0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
21cf0 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
21d00 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
21d10 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
21d20 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
21d30 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
21d40 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
21d50 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
21d60 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
21d70 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
21d80 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
21d90 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
21da0 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
21db0 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
21dc0 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
21dd0 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
21de0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
21df0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
21e00 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
21e10 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
21e20 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
21e30 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
21e40 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
21e50 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
21e60 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
21e70 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
21e80 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
21e90 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
21ea0 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
21eb0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21ec0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21ed0 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
21ee0 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
21ef0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
21f00 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
21f10 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
21f20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
21f30 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
21f40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21f50 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
21f60 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
21f70 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21f80 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21f90 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21fa0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
21fb0 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
21fc0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
21fd0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21fe0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21ff0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
22000 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
22010 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22020 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22030 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22040 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
22050 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
22060 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
22070 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22080 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22090 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
220a0 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
220b0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
220c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
220d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
220e0 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
220f0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
22100 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
22110 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22120 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22130 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
22140 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
22150 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
22160 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22170 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22180 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
22190 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
221a0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
221b0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
221c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
221d0 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
221e0 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
221f0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
22200 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22210 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22220 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
22230 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
22240 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
22250 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22260 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22270 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
22280 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
22290 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
222a0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
222b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
222c0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
222d0 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
222e0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
222f0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22300 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
22310 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
22320 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
22330 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
22340 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22350 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
22360 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
22370 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
22380 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22390 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
223a0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
223b0 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
223c0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
223d0 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
223e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
223f0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
22400 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
22410 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
22420 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22430 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22440 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
22450 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
22460 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
22470 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22480 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22490 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
224a0 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
224b0 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
224c0 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
224d0 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
224e0 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
224f0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
22500 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22510 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
22520 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22530 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
22540 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
22550 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22560 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22570 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22580 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
22590 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
225a0 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
225b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
225c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
225d0 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
225e0 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
225f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
22600 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
22610 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22620 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
22630 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
22640 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
22650 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22660 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22670 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
22680 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
22690 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
226a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
226b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
226c0 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
226d0 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
226e0 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
226f0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22700 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
22710 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
22720 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
22730 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
22740 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22750 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
22760 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
22770 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
22780 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
22790 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
227a0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
227b0 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
227c0 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
227d0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
227e0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
227f0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
22800 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
22810 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
22820 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
22830 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
22840 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
22850 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
22860 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
22870 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
22880 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
22890 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
228a0 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
228b0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
228c0 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
228d0 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
228e0 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
228f0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
22900 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
22910 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
22920 4c 49 54 45 5f 52 45 43 55 52 53 49 56 45 20 20  LITE_RECURSIVE  
22930 20 20 20 20 20 20 20 20 20 20 33 33 20 20 20 2f            33   /
22940 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
22950 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22960 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    */../*.** CAPI
22970 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
22980 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
22990 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  tions.** METHOD:
229a0 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54   sqlite3.**.** T
229b0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
229c0 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20  gister callback 
229d0 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63  functions that c
229e0 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a  an be used for.*
229f0 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72  * tracing and pr
22a00 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63  ofiling the exec
22a10 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61  ution of SQL sta
22a20 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  tements..**.** ^
22a30 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
22a40 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
22a50 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63   by sqlite3_trac
22a60 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  e() is invoked a
22a70 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d  t.** various tim
22a80 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73  es when an SQL s
22a90 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e  tatement is bein
22aa0 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65  g run by [sqlite
22ab0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54  3_step()]..** ^T
22ac0 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  he sqlite3_trace
22ad0 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  () callback is i
22ae0 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54  nvoked with a UT
22af0 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  F-8 rendering of
22b00 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74   the.** SQL stat
22b10 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68  ement text as th
22b20 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73  e statement firs
22b30 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69  t begins executi
22b40 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f  ng..** ^(Additio
22b50 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63  nal sqlite3_trac
22b60 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69  e() callbacks mi
22b70 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20  ght occur.** as 
22b80 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73  each triggered s
22b90 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74  ubprogram is ent
22ba0 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62  ered.  The callb
22bb0 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72  acks for trigger
22bc0 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55  s.** contain a U
22bd0 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74  TF-8 SQL comment
22be0 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73   that identifies
22bf0 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a   the trigger.)^.
22c00 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
22c10 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d  E_TRACE_SIZE_LIM
22c20 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  IT] compile-time
22c30 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
22c40 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20  sed to limit.** 
22c50 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62  the length of [b
22c60 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20  ound parameter] 
22c70 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65  expansion in the
22c80 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74   output of sqlit
22c90 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a  e3_trace()..**.*
22ca0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
22cb0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
22cc0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
22cd0 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
22ce0 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
22cf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
22d00 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
22d10 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
22d20 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
22d30 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
22d40 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
22d50 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
22d60 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
22d70 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
22d80 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
22d90 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
22da0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
22db0 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
22dc0 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
22dd0 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
22de0 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
22df0 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
22e00 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
22e10 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
22e20 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
22e30 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
22e40 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
22e50 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
22e60 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
22e70 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
22e80 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
22e90 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
22ea0 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
22eb0 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
22ec0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
22ed0 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
22ee0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
22ef0 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
22f00 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
22f10 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
22f20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
22f30 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te..*/.SQLITE_AP
22f40 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53  I void *SQLITE_S
22f50 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74  TDCALL sqlite3_t
22f60 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76  race(sqlite3*, v
22f70 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69  oid(*xTrace)(voi
22f80 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  d*,const char*),
22f90 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f   void*);.SQLITE_
22fa0 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52  API SQLITE_EXPER
22fb0 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 53 51  IMENTAL void *SQ
22fc0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
22fd0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
22fe0 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
22ff0 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
23000 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
23010 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
23020 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
23030 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
23040 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
23050 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
23060 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  3.**.** ^The sql
23070 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
23080 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
23090 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
230a0 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
230b0 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
230c0 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
230d0 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
230e0 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
230f0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
23100 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
23110 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
23120 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
23130 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
23140 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
23150 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
23160 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
23170 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
23180 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
23190 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
231a0 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
231b0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
231c0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
231d0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
231e0 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
231f0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
23200 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
23210 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70  eter N is the ap
23220 70 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72  proximate number
23230 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
23240 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
23250 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
23260 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
23270 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
23280 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
23290 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20  he callback X.  
232a0 5e 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68  ^If N is less th
232b0 61 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20  an one then the 
232c0 70 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64  progress.** hand
232d0 6c 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e  ler is disabled.
232e0 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73  .**.** ^Only a s
232f0 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68  ingle progress h
23300 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65  andler may be de
23310 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d  fined at one tim
23320 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61  e per.** [databa
23330 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20  se connection]; 
23340 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72  setting a new pr
23350 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
23360 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c  ancels the.** ol
23370 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67  d one.  ^Setting
23380 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20   parameter X to 
23390 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68  NULL disables th
233a0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
233b0 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67  er..** ^The prog
233c0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20  ress handler is 
233d0 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79  also disabled by
233e0 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20   setting N to a 
233f0 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68  value less.** th
23400 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  an 1..**.** ^If 
23410 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c  the progress cal
23420 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
23430 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72  n-zero, the oper
23440 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65  ation is.** inte
23450 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66  rrupted.  This f
23460 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73  eature can be us
23470 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
23480 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75  a.** "Cancel" bu
23490 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72  tton on a GUI pr
234a0 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f  ogress dialog bo
234b0 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f  x..**.** The pro
234c0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
234d0 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20  llback must not 
234e0 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74  do anything that
234f0 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20   will modify.** 
23500 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
23510 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
23520 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73  oked the progres
23530 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f  s handler..** No
23540 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
23550 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
23560 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
23570 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
23580 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
23590 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
235a0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
235b0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
235c0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
235d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
235e0 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  id SQLITE_STDCAL
235f0 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  L sqlite3_progre
23600 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
23610 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
23620 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
23630 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
23640 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
23650 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
23660 69 6f 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54  ion.** CONSTRUCT
23670 4f 52 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a  OR: sqlite3.**.*
23680 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
23690 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
236a0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
236b0 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
236c0 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
236d0 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
236e0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
236f0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
23700 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
23710 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
23720 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
23730 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
23740 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
23750 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
23760 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
23770 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
23780 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
23790 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
237a0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
237b0 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
237c0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
237d0 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
237e0 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
237f0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
23800 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
23810 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
23820 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
23830 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
23840 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
23850 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
23860 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
23870 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
23880 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
23890 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
238a0 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
238b0 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
238c0 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
238d0 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
238e0 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
238f0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
23900 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
23910 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
23920 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
23930 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
23940 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
23950 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
23960 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
23970 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
23980 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
23990 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
239a0 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
239b0 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
239c0 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
239d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
239e0 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69  ault encoding wi
239f0 6c 6c 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20  ll be UTF-8 for 
23a00 64 61 74 61 62 61 73 65 73 20 63 72 65 61 74 65  databases create
23a10 64 20 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  d using.** sqlit
23a20 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
23a30 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
23a40 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e   ^The default en
23a50 63 6f 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62  coding for datab
23a60 61 73 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  ases.** created 
23a70 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70  using sqlite3_op
23a80 65 6e 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55  en16() will be U
23a90 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
23aa0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
23ab0 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
23ac0 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
23ad0 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
23ae0 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
23af0 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
23b00 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
23b10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
23b20 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
23b30 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
23b40 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
23b50 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
23b60 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
23b70 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
23b80 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
23b90 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
23ba0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
23bb0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
23bc0 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
23bd0 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
23be0 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
23bf0 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
23c00 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
23c10 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
23c20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
23c30 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
23c40 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
23c50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
23c60 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
23c70 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
23c80 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
23c90 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
23ca0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
23cb0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
23cc0 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
23cd0 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
23ce0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
23cf0 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
23d00 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
23d10 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
23d20 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
23d30 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
23d40 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
23d50 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
23d60 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
23d70 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
23d80 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
23d90 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
23da0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
23db0 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
23dc0 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
23dd0 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
23de0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
23df0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
23e00 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
23e10 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
23e20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
23e30 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
23e40 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
23e50 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
23e60 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
23e70 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
23e80 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
23e90 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
23ea0 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
23eb0 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
23ec0 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
23ed0 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
23ee0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
23ef0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
23f00 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
23f10 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
23f20 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
23f30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
23f40 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
23f50 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
23f60 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
23f70 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
23f80 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
23f90 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
23fa0 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
23fb0 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
23fc0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
23fd0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
23fe0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
23ff0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
24000 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
24010 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
24020 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24030 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
24040 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
24050 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
24060 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
24070 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
24080 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
24090 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
240a0 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
240b0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
240c0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
240d0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
240e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
240f0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
24100 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
24110 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
24120 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
24130 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
24140 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
24150 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
24160 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
24170 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
24180 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
24190 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
241a0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
241b0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
241c0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
241d0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
241e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
241f0 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
24200 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
24210 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
24220 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
24230 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
24240 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
24250 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
24260 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
24270 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
24280 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
24290 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
242a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
242b0 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
242c0 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
242d0 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
242e0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
242f0 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
24300 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
24310 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
24320 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
24330 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
24340 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
24350 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
24360 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
24370 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24380 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
24390 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
243a0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
243b0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
243c0 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
243d0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
243e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
243f0 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
24400 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
24410 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
24420 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
24430 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
24440 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
24450 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
24460 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24470 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
24480 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
24490 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
244a0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
244b0 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
244c0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
244d0 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
244e0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
244f0 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
24500 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
24510 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
24520 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
24530 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
24540 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
24550 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
24560 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
24570 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
24580 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
24590 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
245a0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
245b0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
245c0 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
245d0 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
245e0 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
245f0 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
24600 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
24610 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
24620 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
24630 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
24640 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
24650 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
24660 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
24670 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
24680 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
24690 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
246a0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
246b0 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
246c0 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
246d0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
246e0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
246f0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
24700 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
24710 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
24720 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
24730 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
24740 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
24750 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
24760 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
24770 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
24780 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
24790 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
247a0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
247b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
247c0 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
247d0 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
247e0 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
247f0 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
24800 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
24810 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
24820 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
24830 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
24840 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
24850 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
24860 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
24870 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
24880 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
24890 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
248a0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
248b0 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
248c0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
248d0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
248e0 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
248f0 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
24900 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
24910 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
24920 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
24930 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
24940 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
24950 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
24960 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
24970 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
24980 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
24990 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
249a0 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
249b0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
249c0 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
249d0 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
249e0 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
249f0 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
24a00 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
24a10 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
24a20 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
24a30 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
24a40 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
24a50 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
24a60 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
24a70 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
24a80 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
24a90 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
24aa0 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
24ab0 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
24ac0 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
24ad0 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
24ae0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
24af0 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
24b00 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
24b10 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
24b20 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
24b30 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
24b40 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
24b50 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
24b60 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
24b70 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
24b80 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
24b90 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
24ba0 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
24bb0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
24bc0 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
24bd0 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
24be0 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
24bf0 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
24c00 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
24c10 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
24c20 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
24c30 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
24c40 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
24c50 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
24c60 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
24c70 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
24c80 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
24c90 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
24ca0 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
24cb0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
24cc0 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
24cd0 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
24ce0 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
24cf0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
24d00 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
24d10 68 2e 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64  h. .** ^(On wind
24d20 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63  ows, the first c
24d30 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61  omponent of an a
24d40 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a  bsolute path .**
24d50 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63   is a drive spec
24d60 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20  ification (e.g. 
24d70 22 43 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  "C:").)^.**.** [
24d80 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20  [core URI query 
24d90 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20  parameters]].** 
24da0 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  The query compon
24db0 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79  ent of a URI may
24dc0 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74   contain paramet
24dd0 65 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74  ers that are int
24de0 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68  erpreted.** eith
24df0 65 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73  er by SQLite its
24e00 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46  elf, or by a [VF
24e10 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69  S | custom VFS i
24e20 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a  mplementation]..
24e30 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74  ** SQLite and it
24e40 73 20 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65  s built-in [VFSe
24e50 73 5d 20 69 6e 74 65 72 70 72 65 74 20 74 68 65  s] interpret the
24e60 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75  .** following qu
24e70 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a  ery parameters:.
24e80 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20  **.** <ul>.**   
24e90 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a  <li> <b>vfs</b>:
24ea0 20 5e 54 68 65 20 22 76 66 73 22 20 70 61 72 61   ^The "vfs" para
24eb0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75 73 65  meter may be use
24ec0 64 20 74 6f 20 73 70 65 63 69 66 79 20 74 68 65  d to specify the
24ed0 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20   name of.**     
24ee0 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61  a VFS object tha
24ef0 74 20 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f  t provides the o
24f00 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
24f10 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 73  interface that s
24f20 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20  hould.**     be 
24f30 75 73 65 64 20 74 6f 20 61 63 63 65 73 73 20 74  used to access t
24f40 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
24f50 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68   on disk. ^If th
24f60 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  is option is set
24f70 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d   to.**     an em
24f80 70 74 79 20 73 74 72 69 6e 67 20 74 68 65 20 64  pty string the d
24f90 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63  efault VFS objec
24fa0 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63  t is used. ^Spec
24fb0 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77  ifying an unknow
24fc0 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20  n.**     VFS is 
24fd0 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71  an error. ^If sq
24fe0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
24ff0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
25000 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  vfs option is.**
25010 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68       present, th
25020 65 6e 20 74 68 65 20 56 46 53 20 73 70 65 63 69  en the VFS speci
25030 66 69 65 64 20 62 79 20 74 68 65 20 6f 70 74 69  fied by the opti
25040 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65 64 65  on takes precede
25050 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20  nce over.**     
25060 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65 64  the value passed
25070 20 61 73 20 74 68 65 20 66 6f 75 72 74 68 20 70   as the fourth p
25080 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
25090 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
250a0 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d  *.**   <li> <b>m
250b0 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d  ode</b>: ^(The m
250c0 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ode parameter ma
250d0 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
250e0 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a  er "ro", "rw",.*
250f0 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20  *     "rwc", or 
25100 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70  "memory". Attemp
25110 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74  ting to set it t
25120 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  o any other valu
25130 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65  e is.**     an e
25140 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20  rror)^. .**     
25150 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70 65 63  ^If "ro" is spec
25160 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20  ified, then the 
25170 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
25180 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ed for read-only
25190 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c   .**     access,
251a0 20 6a 75 73 74 20 61 73 20 69 66 20 74 68 65 20   just as if the 
251b0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
251c0 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20  DONLY] flag had 
251d0 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20  been set in the 
251e0 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20 61 72  .**     third ar
251f0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
25200 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66  3_open_v2(). ^If
25210 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
25220 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20   is set to .**  
25230 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68     "rw", then th
25240 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
25250 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72  ened for read-wr
25260 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65  ite (but not cre
25270 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63  ate) .**     acc
25280 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54  ess, as if SQLIT
25290 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
252a0 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45   (but not SQLITE
252b0 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61  _OPEN_CREATE) ha
252c0 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73  d .**     been s
252d0 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22  et. ^Value "rwc"
252e0 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
252f0 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a  o setting both .
25300 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
25310 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64  EN_READWRITE and
25320 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
25330 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  ATE.  ^If the mo
25340 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  de option is.** 
25350 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f      set to "memo
25360 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65 20  ry" then a pure 
25370 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62  [in-memory datab
25380 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20  ase] that never 
25390 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20  reads.**     or 
253a0 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b  writes from disk
253b0 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73   is used. ^It is
253c0 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
253d0 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
253e0 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65  .**     the mode
253f0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
25400 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63 74  is less restrict
25410 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73 70  ive than that sp
25420 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20  ecified by.**   
25430 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73    the flags pass
25440 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  ed in the third 
25450 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
25460 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a  ite3_open_v2()..
25470 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  **.**   <li> <b>
25480 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20  cache</b>: ^The 
25490 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
254a0 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
254b0 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f 72  ther "shared" or
254c0 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74 65  .**     "private
254d0 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74  ". ^Setting it t
254e0 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65 71  o "shared" is eq
254f0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
25500 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53  ing the.**     S
25510 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
25520 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74 68  DCACHE bit in th
25530 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
25540 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20   passed to.**   
25550 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76    sqlite3_open_v
25560 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68  2(). ^Setting th
25570 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
25580 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20 69  r to "private" i
25590 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61  s .**     equiva
255a0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
255b0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
255c0 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69 74  PRIVATECACHE bit
255d0 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c  ..**     ^If sql
255e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
255f0 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 22  s used and the "
25600 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65 72  cache" parameter
25610 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a   is present in.*
25620 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c 65  *     a URI file
25630 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20  name, its value 
25640 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62 65  overrides any be
25650 68 61 76 69 6f 72 20 72 65 71 75 65 73 74 65 64  havior requested
25660 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20   by setting.**  
25670 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50     SQLITE_OPEN_P
25680 52 49 56 41 54 45 43 41 43 48 45 20 6f 72 20 53  RIVATECACHE or S
25690 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
256a0 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a  DCACHE flag..**.
256b0 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77  **  <li> <b>psow
256c0 3c 2f 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20  </b>: ^The psow 
256d0 70 61 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61  parameter indica
256e0 74 65 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e  tes whether or n
256f0 6f 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70  ot the.**     [p
25700 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72 69  owersafe overwri
25710 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65  te] property doe
25720 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70  s or does not ap
25730 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20  ply to the.**   
25740 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20    storage media 
25750 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61 74  on which the dat
25760 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69 64  abase file resid
25770 65 73 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  es..**.**  <li> 
25780 3c 62 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e  <b>nolock</b>: ^
25790 54 68 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d  The nolock param
257a0 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61  eter is a boolea
257b0 6e 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  n query paramete
257c0 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69  r.**     which i
257d0 66 20 73 65 74 20 64 69 73 61 62 6c 65 73 20 66  f set disables f
257e0 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72  ile locking in r
257f0 6f 6c 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20  ollback journal 
25800 6d 6f 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20  modes.  This.** 
25810 20 20 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f      is useful fo
25820 72 20 61 63 63 65 73 73 69 6e 67 20 61 20 64 61  r accessing a da
25830 74 61 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65  tabase on a file
25840 73 79 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73  system that does
25850 20 6e 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70   not.**     supp
25860 6f 72 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61  ort locking.  Ca
25870 75 74 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65  ution:  Database
25880 20 63 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68   corruption migh
25890 74 20 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a  t result if two.
258a0 2a 2a 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70  **     or more p
258b0 72 6f 63 65 73 73 65 73 20 77 72 69 74 65 20 74  rocesses write t
258c0 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  o the same datab
258d0 61 73 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20  ase and any one 
258e0 6f 66 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20  of those.**     
258f0 70 72 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e  processes uses n
25900 6f 6c 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20  olock=1..**.**  
25910 3c 6c 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c  <li> <b>immutabl
25920 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75  e</b>: ^The immu
25930 74 61 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20  table parameter 
25940 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65  is a boolean que
25950 72 79 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65  ry.**     parame
25960 74 65 72 20 74 68 61 74 20 69 6e 64 69 63 61 74  ter that indicat
25970 65 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  es that the data
25980 62 61 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f  base file is sto
25990 72 65 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65  red on.**     re
259a0 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20  ad-only media.  
259b0 5e 57 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20  ^When immutable 
259c0 69 73 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61  is set, SQLite a
259d0 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
259e0 2a 2a 20 20 20 20 20 64 61 74 61 62 61 73 65 20  **     database 
259f0 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63  file cannot be c
25a00 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20  hanged, even by 
25a10 61 20 70 72 6f 63 65 73 73 20 77 69 74 68 20 68  a process with h
25a20 69 67 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69  igher.**     pri
25a30 76 69 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74  vilege, and so t
25a40 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
25a50 70 65 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20  pened read-only 
25a60 61 6e 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a  and all locking.
25a70 2a 2a 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67  **     and chang
25a80 65 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64  e detection is d
25a90 69 73 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f  isabled.  Cautio
25aa0 6e 3a 20 53 65 74 74 69 6e 67 20 74 68 65 20 69  n: Setting the i
25ab0 6d 6d 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20  mmutable.**     
25ac0 70 72 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61  property on a da
25ad0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
25ae0 20 64 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68   does in fact ch
25af0 61 6e 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a  ange can result.
25b00 2a 2a 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72  **     in incorr
25b10 65 63 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  ect query result
25b20 73 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45  s and/or [SQLITE
25b30 5f 43 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73  _CORRUPT] errors
25b40 2e 0a 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73  ..**     See als
25b50 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  o: [SQLITE_IOCAP
25b60 5f 49 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20  _IMMUTABLE]..** 
25b70 20 20 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a        .** </ul>.
25b80 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
25b90 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
25ba0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
25bb0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
25bc0 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
25bd0 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
25be0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
25bf0 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
25c00 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
25c10 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
25c20 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
25c30 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
25c40 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
25c50 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
25c60 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
25c70 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
25c80 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
25c90 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
25ca0 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
25cb0 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
25cc0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
25cd0 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
25ce0 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
25cf0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
25d00 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
25d10 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
25d20 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
25d30 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
25d40 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
25d50 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
25d60 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
25d70 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
25d80 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
25d90 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
25da0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
25db0 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
25dc0 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
25dd0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
25de0 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
25df0 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
25e00 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
25e10 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
25e20 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
25e30 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
25e40 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
25e50 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
25e60 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
25e70 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
25e80 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
25e90 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
25ea0 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
25eb0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
25ec0 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
25ed0 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
25ee0 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
25ef0 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
25f00 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
25f10 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
25f20 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
25f30 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
25f40 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
25f50 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
25f60 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
25f70 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
25f80 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
25f90 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
25fa0 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
25fb0 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
25fc0 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
25fd0 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
25fe0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
25ff0 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
26000 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
26010 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
26020 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
26030 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
26040 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
26050 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
26060 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
26070 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
26080 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
26090 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
260a0 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
260b0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
260c0 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
260d0 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
260e0 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
260f0 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
26100 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
26110 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
26120 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26130 3f 76 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c  ?vfs=unix-dotfil
26140 65 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20  e <td>.**       
26150 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68     Open file "/h
26160 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26170 22 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69  ". Use the speci
26180 61 6c 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74  al VFS "unix-dot
26190 66 69 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20  file".**        
261a0 20 20 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d    that uses dot-
261b0 66 69 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f  files in place o
261c0 66 20 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79  f posix advisory
261d0 20 6c 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72   locking..** <tr
261e0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
261f0 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
26200 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26210 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
26220 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
26230 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
26240 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
26250 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
26260 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
26270 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
26280 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
26290 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
262a0 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
262b0 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
262c0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
262d0 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
262e0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
262f0 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
26300 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
26310 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
26320 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
26330 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
26340 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
26350 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
26360 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
26370 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
26380 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
26390 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
263a0 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
263b0 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
263c0 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
263d0 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
263e0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
263f0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
26400 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
26410 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
26420 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
26430 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
26440 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
26450 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
26460 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
26470 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
26480 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
26490 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
264a0 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
264b0 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
264c0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
264d0 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
264e0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
264f0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
26500 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
26510 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
26520 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
26530 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
26540 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
26550 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
26560 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
26570 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
26580 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
26590 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
265a0 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
265b0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
265c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
265d0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
265e0 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
265f0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
26600 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74  temporary direct
26610 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a  ory must be set.
26620 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ** prior to call
26630 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
26640 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
26650 65 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77  en_v2().  Otherw
26660 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20  ise, various.** 
26670 66 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65  features that re
26680 71 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66  quire the use of
26690 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73   temporary files
266a0 20 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a   may fail..**.**
266b0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
266c0 74 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f  te3_temp_directo
266d0 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ry].*/.SQLITE_AP
266e0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
266f0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65  CALL sqlite3_ope
26700 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
26710 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
26720 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
26730 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
26740 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
26750 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
26760 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
26770 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
26780 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
26790 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ALL sqlite3_open
267a0 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
267b0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
267c0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
267d0 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
267e0 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
267f0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
26800 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
26810 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
26820 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
26830 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 70  DCALL sqlite3_op
26840 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
26850 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
26860 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
26870 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
26880 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
26890 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
268a0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
268b0 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
268c0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
268d0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
268e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
268f0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
26900 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
26910 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
26920 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
26930 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
26940 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
26950 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
26960 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
26970 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
26980 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
26990 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
269a0 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
269b0 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
269c0 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
269d0 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
269e0 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
269f0 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
26a00 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
26a10 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
26a20 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
26a30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
26a40 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
26a50 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
26a60 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
26a70 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
26a80 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
26a90 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
26aa0 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
26ab0 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
26ac0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
26ad0 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
26ae0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
26af0 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
26b00 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
26b10 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
26b20 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
26b30 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
26b40 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
26b50 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
26b60 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
26b70 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
26b80 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
26b90 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
26ba0 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
26bb0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
26bc0 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
26bd0 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
26be0 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
26bf0 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
26c00 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
26c10 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
26c20 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
26c30 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
26c40 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
26c50 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
26c60 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
26c70 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
26c80 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
26c90 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
26ca0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
26cb0 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
26cc0 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
26cd0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
26ce0 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
26cf0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
26d00 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
26d10 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
26d20 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
26d30 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
26d40 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
26d50 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
26d60 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
26d70 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
26d80 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
26d90 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
26da0 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
26db0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
26dc0 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
26dd0 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
26de0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
26df0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
26e00 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
26e10 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
26e20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
26e30 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
26e40 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
26e50 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
26e60 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
26e70 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
26e80 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
26e90 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
26ea0 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
26eb0 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
26ec0 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
26ed0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
26ee0 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
26ef0 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
26f00 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
26f10 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
26f20 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
26f30 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
26f40 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
26f50 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
26f60 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
26f70 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
26f80 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
26f90 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
26fa0 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
26fb0 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
26fc0 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
26fd0 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
26fe0 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
26ff0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
27000 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
27010 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
27020 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
27030 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
27040 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
27050 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
27060 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
27070 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
27080 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
27090 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
270a0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
270b0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
270c0 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
270d0 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
270e0 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
270f0 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
27100 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
27110 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
27120 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
27130 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
27140 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
27150 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63  _uri_parameter(c
27160 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
27170 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  name, const char
27180 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54   *zParam);.SQLIT
27190 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
271a0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
271b0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e  _uri_boolean(con
271c0 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
271d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
271e0 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74  am, int bDefault
271f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
27200 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49  lite3_int64 SQLI
27210 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
27220 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
27230 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
27240 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
27250 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
27260 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
27270 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
27280 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
27290 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ite3.**.** ^If t
272a0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73  he most recent s
272b0 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c  qlite3_* API cal
272c0 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  l associated wit
272d0 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  h .** [database 
272e0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 66 61  connection] D fa
272f0 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 73  iled, then the s
27300 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 44  qlite3_errcode(D
27310 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  ) interface.** r
27320 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
27330 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
27340 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 72 65   or [extended re
27350 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
27360 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c 6c 2e  hat.** API call.
27370 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73 74 20  .** If the most 
27380 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
27390 77 61 73 20 73 75 63 63 65 73 73 66 75 6c 2c 0a  was successful,.
273a0 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
273b0 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
273c0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
273d0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
273e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
273f0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
27400 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
27410 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
27420 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
27430 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
27440 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
27450 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
27460 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
27470 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
27480 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
27490 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
274a0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
274b0 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
274c0 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
274d0 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
274e0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
274f0 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
27500 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
27510 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
27520 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
27530 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
27540 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
27550 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
27560 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
27570 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
27580 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
27590 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
275a0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
275b0 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
275c0 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
275d0 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
275e0 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
275f0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
27600 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
27610 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
27620 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
27630 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
27640 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27650 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
27660 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
27670 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
27680 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
27690 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
276a0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
276b0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
276c0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
276d0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
276e0 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
276f0 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
27700 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
27710 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
27720 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
27730 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
27740 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
27750 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
27760 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
27770 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
27780 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
27790 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
277a0 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
277b0 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
277c0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
277d0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
277e0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
277f0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
27800 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
27810 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
27820 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
27830 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
27840 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
27850 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
27860 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
27870 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
27880 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
27890 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
278a0 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
278b0 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
278c0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
278d0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
278e0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
278f0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
27900 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
27910 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
27920 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
27930 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
27940 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
27950 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
27960 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
27970 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
27980 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
27990 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
279a0 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
279b0 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
279c0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
279d0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
279e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
279f0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
27a00 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
27a10 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
27a20 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
27a30 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  set..*/.SQLITE_A
27a40 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
27a50 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72  DCALL sqlite3_er
27a60 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64  rcode(sqlite3 *d
27a70 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  b);.SQLITE_API i
27a80 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
27a90 4c 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  L sqlite3_extend
27aa0 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
27ab0 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
27ac0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
27ad0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
27ae0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
27af0 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f  lite3*);.SQLITE_
27b00 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
27b10 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
27b20 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
27b30 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54  sqlite3*);.SQLIT
27b40 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
27b50 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
27b60 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
27b70 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
27b80 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20  I3REF: Prepared 
27b90 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
27ba0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
27bb0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27bc0 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
27bd0 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
27be0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
27bf0 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
27c00 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
27c10 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
27c20 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  .** has been com
27c30 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72  piled into binar
27c40 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65  y form and is re
27c50 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61  ady to be evalua
27c60 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b  ted..**.** Think
27c70 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61   of each SQL sta
27c80 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61  tement as a sepa
27c90 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72  rate computer pr
27ca0 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f  ogram.  The.** o
27cb0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
27cc0 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e   is source code.
27cd0 20 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61    A prepared sta
27ce0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a  tement object .*
27cf0 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65  * is the compile
27d00 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20  d object code.  
27d10 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20  All SQL must be 
27d20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
27d30 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
27d40 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74  tement before it
27d50 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a   can be run..**.
27d60 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c  ** The life-cycl
27d70 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20  e of a prepared 
27d80 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
27d90 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69   usually goes li
27da0 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
27db0 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
27dc0 74 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20  te the prepared 
27dd0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
27de0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
27df0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a  prepare_v2()]..*
27e00 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
27e10 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  es to [parameter
27e20 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
27e30 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
27e40 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
27e50 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
27e60 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
27e70 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
27e80 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
27e90 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
27ea0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
27eb0 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
27ec0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
27ed0 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
27ee0 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
27ef0 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
27f00 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
27f10 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
27f20 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
27f30 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
27f40 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
27f50 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
27f60 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
27f70 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
27f80 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
27f90 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20  -time Limits.** 
27fa0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
27fb0 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
27fc0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
27fd0 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
27fe0 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
27ff0 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
28000 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
28010 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
28020 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
28030 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
28040 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
28050 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
28060 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
28070 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
28080 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
28090 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
280a0 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
280b0 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
280c0 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
280d0 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
280e0 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
280f0 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
28100 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
28110 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
28120 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a  t construct.)^.*
28130 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
28140 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
28150 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
28160 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
28170 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61  ged..** ^(For ea
28180 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  ch limit categor
28190 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c  y SQLITE_LIMIT_<
281a0 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65  i>NAME</i> there
281b0 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
281c0 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
281d0 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20  ound].** set at 
281e0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20  compile-time by 
281f0 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  a C preprocessor
28200 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a   macro called.**
28210 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54   [limits | SQLIT
28220 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  E_MAX_<i>NAME</i
28230 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  >]..** (The "_LI
28240 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
28250 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
28260 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
28270 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
28280 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
28290 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
282a0 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
282b0 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
282c0 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
282d0 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
282e0 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
282f0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
28300 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61  he limit was cha
28310 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73  nged, the .** [s
28320 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20  qlite3_limit()] 
28330 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28340 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  s the prior valu
28350 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a  e of the limit..
28360 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69  ** ^Hence, to fi
28370 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  nd the current v
28380 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20  alue of a limit 
28390 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67  without changing
283a0 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69   it,.** simply i
283b0 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72  nvoke this inter
283c0 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68  face with the th
283d0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ird parameter se
283e0 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52  t to -1..**.** R
283f0 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
28400 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
28410 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
28420 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
28430 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
28440 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
28450 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
28460 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
28470 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
28480 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
28490 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
284a0 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
284b0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
284c0 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
284d0 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
284e0 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
284f0 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
28500 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
28510 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
28520 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
28530 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
28540 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
28550 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
28560 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
28570 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
28580 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
28590 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
285a0 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
285b0 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
285c0 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
285d0 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
285e0 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
285f0 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
28600 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
28610 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
28620 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
28630 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
28640 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
28650 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
28660 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
28670 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
28680 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
28690 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
286a0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
286b0 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
286c0 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
286d0 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
286e0 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
286f0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
28700 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
28710 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
28720 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
28730 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
28740 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c  releases..*/.SQL
28750 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
28760 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
28770 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33  e3_limit(sqlite3
28780 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e  *, int id, int n
28790 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ewVal);../*.** C
287a0 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
287b0 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69  e Limit Categori
287c0 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
287d0 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d  {limit category}
287e0 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72   {*limit categor
287f0 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ies}.**.** These
28800 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e   constants defin
28810 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72  e various perfor
28820 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20  mance limits.** 
28830 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65  that can be lowe
28840 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20  red at run-time 
28850 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
28860 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20  imit()]..** The 
28870 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20  synopsis of the 
28880 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20  meanings of the 
28890 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69  various limits i
288a0 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a  s shown below..*
288b0 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * Additional inf
288c0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69  ormation is avai
288d0 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73  lable at [limits
288e0 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c   | Limits in SQL
288f0 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  ite]..**.** <dl>
28900 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
28910 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  IT_LENGTH]] ^(<d
28920 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
28930 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
28940 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
28950 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
28960 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
28970 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
28980 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  <dd>)^.**.** [[S
28990 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
289a0 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  LENGTH]] ^(<dt>S
289b0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f  QLITE_LIMIT_SQL_
289c0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
289d0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
289e0 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20  ength of an SQL 
289f0 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79  statement, in by
28a00 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  tes.</dd>)^.**.*
28a10 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
28a20 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e  _COLUMN]] ^(<dt>
28a30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
28a40 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  UMN</dt>.** <dd>
28a50 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
28a60 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
28a70 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74   a table definit
28a80 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a  ion or in the.**
28a90 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61   result set of a
28aa0 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65   [SELECT] or the
28ab0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
28ac0 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e  of columns in an
28ad0 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20   index.** or in 
28ae0 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47  an ORDER BY or G
28af0 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c  ROUP BY clause.<
28b00 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
28b10 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
28b20 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53  _DEPTH]] ^(<dt>S
28b30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
28b40 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
28b50 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
28b60 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
28b70 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
28b80 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
28b90 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
28ba0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
28bb0 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51  ELECT]] ^(<dt>SQ
28bc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
28bd0 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a  UND_SELECT</dt>.
28be0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
28bf0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72  um number of ter
28c00 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64  ms in a compound
28c10 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e   SELECT statemen
28c20 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  t.</dd>)^.**.** 
28c30 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
28c40 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53  DBE_OP]] ^(<dt>S
28c50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
28c60 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  _OP</dt>.** <dd>
28c70 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
28c80 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f  er of instructio
28c90 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20  ns in a virtual 
28ca0 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a  machine program.
28cb0 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  ** used to imple
28cc0 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74  ment an SQL stat
28cd0 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d  ement.  This lim
28ce0 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  it is not curren
28cf0 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c  tly.** enforced,
28d00 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67   though that mig
28d10 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73  ht be added in s
28d20 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61  ome future relea
28d30 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
28d40 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
28d50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
28d60 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64  CTION_ARG]] ^(<d
28d70 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  t>SQLITE_LIMIT_F
28d80 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e  UNCTION_ARG</dt>
28d90 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28da0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  mum number of ar
28db0 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e  guments on a fun
28dc0 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ction.</dd>)^.**
28dd0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
28de0 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28  IT_ATTACHED]] ^(
28df0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28e00 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a  _ATTACHED</dt>.*
28e10 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
28e20 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54  m number of [ATT
28e30 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64  ACH | attached d
28e40 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64  atabases].)^</dd
28e50 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
28e60 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
28e70 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20  ERN_LENGTH]].** 
28e80 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
28e90 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
28ea0 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
28eb0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c  dd>The maximum l
28ec0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74  ength of the pat
28ed0 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f  tern argument to
28ee0 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a   the [LIKE] or.*
28ef0 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f  * [GLOB] operato
28f00 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  rs.</dd>)^.**.**
28f10 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
28f20 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d  VARIABLE_NUMBER]
28f30 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
28f40 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
28f50 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20  _NUMBER</dt>.** 
28f60 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
28f70 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20  index number of 
28f80 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  any [parameter] 
28f90 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
28fa0 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ent.)^.**.** [[S
28fb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
28fc0 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  GER_DEPTH]] ^(<d
28fd0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  t>SQLITE_LIMIT_T
28fe0 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74  RIGGER_DEPTH</dt
28ff0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29000 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65  imum depth of re
29010 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67  cursion for trig
29020 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  gers.</dd>)^.**.
29030 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29040 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41 44 53  T_WORKER_THREADS
29050 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
29060 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52  LIMIT_WORKER_THR
29070 45 41 44 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EADS</dt>.** <dd
29080 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
29090 62 65 72 20 6f 66 20 61 75 78 69 6c 69 61 72 79  ber of auxiliary
290a0 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
290b0 74 68 61 74 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  that a single.**
290c0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
290d0 6d 65 6e 74 5d 20 6d 61 79 20 73 74 61 72 74 2e  ment] may start.
290e0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
290f0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
29100 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
29110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29120 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
29130 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
29140 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
29150 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
29160 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
29170 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
29180 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
29190 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
291a0 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
291b0 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
291c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
291d0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
291e0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
291f0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
29200 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
29210 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
29220 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
29230 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
29240 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
29250 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29260 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
29270 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
29280 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29290 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
292a0 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
292b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
292c0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
292d0 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
292e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
292f0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
29300 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 23              10.#
29310 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29320 4d 49 54 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  MIT_WORKER_THREA
29330 44 53 20 20 20 20 20 20 20 20 20 20 20 31 31 0a  DS           11.
29340 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29350 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
29360 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
29370 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
29380 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
29390 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  }.** METHOD: sql
293a0 69 74 65 33 0a 2a 2a 20 43 4f 4e 53 54 52 55 43  ite3.** CONSTRUC
293b0 54 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  TOR: sqlite3_stm
293c0 74 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  t.**.** To execu
293d0 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
293e0 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
293f0 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
29400 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
29410 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
29420 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
29430 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
29440 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
29450 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
29460 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
29470 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
29480 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
29490 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
294a0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
294b0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
294c0 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
294d0 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
294e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
294f0 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
29500 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
29510 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
29520 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
29530 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
29540 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
29550 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
29560 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
29570 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
29580 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
29590 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
295a0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
295b0 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
295c0 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
295d0 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
295e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
295f0 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
29600 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
29610 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
29620 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
29630 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20  en zSql is read 
29640 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72  up to the.** fir
29650 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  st zero terminat
29660 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73  or. ^If nByte is
29670 20 70 6f 73 69 74 69 76 65 2c 20 74 68 65 6e 20   positive, then 
29680 69 74 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  it is the.** num
29690 62 65 72 20 6f 66 20 62 79 74 65 73 20 72 65 61  ber of bytes rea
296a0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 49  d from zSql.  ^I
296b0 66 20 6e 42 79 74 65 20 69 73 20 7a 65 72 6f 2c  f nByte is zero,
296c0 20 74 68 65 6e 20 6e 6f 20 70 72 65 70 61 72 65   then no prepare
296d0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
296e0 73 20 67 65 6e 65 72 61 74 65 64 2e 0a 2a 2a 20  s generated..** 
296f0 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
29700 6f 77 73 20 74 68 61 74 20 74 68 65 20 73 75 70  ows that the sup
29710 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
29720 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
29730 74 68 65 6e 0a 2a 2a 20 74 68 65 72 65 20 69 73  then.** there is
29740 20 61 20 73 6d 61 6c 6c 20 70 65 72 66 6f 72 6d   a small perform
29750 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
29760 6f 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  o passing an nBy
29770 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
29780 74 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  t.** is the numb
29790 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
297a0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
297b0 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
297c0 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
297d0 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49  inator..**.** ^I
297e0 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
297f0 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
29800 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
29810 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
29820 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
29830 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
29840 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
29850 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
29860 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
29870 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
29880 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
29890 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
298a0 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
298b0 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
298c0 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
298d0 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
298e0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
298f0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
29900 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29910 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
29920 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
29930 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
29940 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
29950 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
29960 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
29970 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
29980 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
29990 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
299a0 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
299b0 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
299c0 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
299d0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
299e0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
299f0 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
29a00 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
29a10 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
29a20 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
29a30 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
29a40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
29a50 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
29a60 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
29a70 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
29a80 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
29a90 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
29aa0 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
29ab0 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
29ac0 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
29ad0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
29ae0 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
29af0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
29b00 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
29b10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
29b20 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
29b30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29b40 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
29b50 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
29b60 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
29b70 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
29b80 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
29b90 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
29ba0 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
29bb0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
29bc0 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
29bd0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
29be0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
29bf0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
29c00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29c10 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
29c20 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
29c30 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
29c40 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
29c50 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
29c60 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
29c70 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
29c80 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
29c90 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
29ca0 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
29cb0 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
29cc0 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
29cd0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
29ce0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
29cf0 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
29d00 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
29d10 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
29d20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
29d30 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
29d40 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
29d50 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
29d60 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
29d70 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
29d80 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
29d90 61 69 6e 2e 20 41 73 20 6d 61 6e 79 20 61 73 20  ain. As many as 
29da0 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 53 43 48 45  [SQLITE_MAX_SCHE
29db0 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a 20 72 65 74  MA_RETRY].** ret
29dc0 72 69 65 73 20 77 69 6c 6c 20 6f 63 63 75 72 20  ries will occur 
29dd0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 73  before sqlite3_s
29de0 74 65 70 28 29 20 67 69 76 65 73 20 75 70 20 61  tep() gives up a
29df0 6e 64 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  nd returns an er
29e00 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ror..** </li>.**
29e10 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
29e20 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
29e30 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
29e40 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
29e50 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
29e60 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
29e70 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
29e80 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
29e90 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
29ea0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
29eb0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
29ec0 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
29ed0 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
29ee0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
29ef0 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
29f00 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29f10 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
29f20 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
29f30 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
29f40 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
29f50 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
29f60 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
29f70 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
29f80 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
29f90 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
29fa0 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
29fb0 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
29fc0 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
29fd0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
29fe0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
29ff0 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
2a000 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
2a010 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
2a020 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
2a030 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
2a040 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
2a050 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
2a060 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
2a070 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
2a080 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
2a090 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
2a0a0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
2a0b0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
2a0c0 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
2a0d0 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
2a0e0 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
2a0f0 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
2a100 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
2a110 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
2a120 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
2a130 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
2a140 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
2a150 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
2a160 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
2a170 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
2a180 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
2a190 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
2a1a0 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
2a1b0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
2a1c0 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
2a1d0 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
2a1e0 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
2a1f0 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
2a200 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
2a210 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
2a220 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
2a230 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
2a240 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
2a250 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
2a260 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2a270 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
2a280 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
2a290 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
2a2a0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2a2b0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 65 70  ALL sqlite3_prep
2a2c0 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
2a2d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2a2e0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2a2f0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2a300 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2a310 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2a320 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2a330 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2a340 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2a350 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2a360 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2a370 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2a380 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2a390 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2a3a0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2a3b0 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2a3c0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2a3d0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2a3e0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2a3f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2a400 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2a410 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2a420 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2a430 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2a440 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2a450 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2a460 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
2a470 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2a480 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
2a490 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2a4a0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2a4b0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2a4c0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2a4d0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2a4e0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2a4f0 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2a500 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2a510 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
2a520 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2a530 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2a540 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2a550 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2a560 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2a570 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2a580 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
2a590 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2a5a0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2a5b0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2a5c0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2a5d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2a5e0 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2a5f0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2a600 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2a610 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2a620 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2a630 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2a640 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2a650 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2a660 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2a670 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
2a680 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2a690 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2a6a0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2a6b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2a6c0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2a6d0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2a6e0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
2a6f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2a700 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2a710 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
2a720 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
2a730 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2a740 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
2a750 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
2a760 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
2a770 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
2a780 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
2a790 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
2a7a0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
2a7b0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
2a7c0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
2a7d0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
2a7e0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
2a7f0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
2a800 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
2a810 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
2a820 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
2a830 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
2a840 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2a850 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2a860 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
2a870 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
2a880 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
2a890 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
2a8a0 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
2a8b0 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
2a8c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a8d0 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
2a8e0 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
2a8f0 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
2a900 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
2a910 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2a920 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2a930 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  _v2()]..*/.SQLIT
2a940 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2a950 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
2a960 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c   sqlite3_sql(sql
2a970 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2a980 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a990 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
2a9a0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2a9b0 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
2a9c0 61 62 61 73 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a  abase.** METHOD:
2a9d0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2a9e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2a9f0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58  _stmt_readonly(X
2aa00 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2aa10 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
2aa20 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e  ro) if.** and on
2aa30 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70 61  ly if the [prepa
2aa40 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 58  red statement] X
2aa50 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63 74   makes no direct
2aa60 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74   changes to.** t
2aa70 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
2aa80 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
2aa90 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2aaa0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2aab0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2aac0 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74  ons] or.** [virt
2aad0 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67 68  ual tables] migh
2aae0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
2aaf0 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c 79  abase indirectly
2ab00 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65 63   as a side effec
2ab10 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  t.  .** ^(For ex
2ab20 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70 70  ample, if an app
2ab30 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 73  lication defines
2ab40 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76 61   a function "eva
2ab50 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63 61  l()" that .** ca
2ab60 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  lls [sqlite3_exe
2ab70 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 66  c()], then the f
2ab80 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74 61  ollowing SQL sta
2ab90 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20  tement would.** 
2aba0 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
2abb0 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67 68  ase file through
2abc0 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a   side-effects:.*
2abd0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2abe0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c  ><pre>.**    SEL
2abf0 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54 45  ECT eval('DELETE
2ac00 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20   FROM t1') FROM 
2ac10 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  t2;.** </pre></b
2ac20 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
2ac30 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68 65   But because the
2ac40 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
2ac50 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ent does not cha
2ac60 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2ac70 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c   file.** directl
2ac80 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  y, sqlite3_stmt_
2ac90 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64  readonly() would
2aca0 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74 72   still return tr
2acb0 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61  ue.)^.**.** ^Tra
2acc0 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
2acd0 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63 68   statements such
2ace0 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f   as [BEGIN], [CO
2acf0 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b  MMIT], [ROLLBACK
2ad00 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54  ],.** [SAVEPOINT
2ad10 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d  ], and [RELEASE]
2ad20 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f 73   cause sqlite3_s
2ad30 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
2ad40 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a  o return true,.*
2ad50 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61 74  * since the stat
2ad60 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76 65  ements themselve
2ad70 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c  s do not actuall
2ad80 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  y modify the dat
2ad90 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61 74  abase but.** rat
2ada0 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c  her they control
2adb0 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20 77   the timing of w
2adc0 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65 6d  hen other statem
2add0 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65 20  ents modify the 
2ade0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 5e  .** database.  ^
2adf0 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e 64  The [ATTACH] and
2ae00 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65 6d   [DETACH] statem
2ae10 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65 0a  ents also cause.
2ae20 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  ** sqlite3_stmt_
2ae30 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65  readonly() to re
2ae40 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65 2c  turn true since,
2ae50 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74 61   while those sta
2ae60 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67  tements.** chang
2ae70 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  e the configurat
2ae80 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61 73  ion of a databas
2ae90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68  e connection, th
2aea0 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a  ey do not make .
2aeb0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ** changes to th
2aec0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2aed0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73 20   database files 
2aee0 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49  on disk..*/.SQLI
2aef0 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2af00 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2af10 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2af20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2af30 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2af40 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
2af50 20 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53   If A Prepared S
2af60 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65  tatement Has Bee
2af70 6e 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  n Reset.** METHO
2af80 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2af90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2afa0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
2afb0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2afc0 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2afd0 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
2afe0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2aff0 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
2b000 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
2b010 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
2b020 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
2b030 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f  t has not run to
2b040 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f   completion and/
2b050 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62  or has not .** b
2b060 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20  een reset using 
2b070 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2b080 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  )].  ^The sqlite
2b090 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a  3_stmt_busy(S).*
2b0a0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
2b0b0 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69  rns false if S i
2b0c0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2b0d0 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61  .  If S is not a
2b0e0 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   .** NULL pointe
2b0f0 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  r and is not a p
2b100 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
2b110 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
2b120 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
2b130 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2b140 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2b150 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
2b160 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
2b170 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
2b180 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63  can be used in c
2b190 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69  ombination [sqli
2b1a0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
2b1b0 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  .** to locate al
2b1c0 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
2b1d0 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
2b1e0 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
2b1f0 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   .** connection 
2b200 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64  that are in need
2b210 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e   of being reset.
2b220 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
2b230 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70  ed,.** for examp
2b240 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69  le, in diagnosti
2b250 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65  c routines to se
2b260 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65  arch for prepare
2b270 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  d .** statements
2b280 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e   that are holdin
2b290 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
2b2a0 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  open..*/.SQLITE_
2b2b0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2b2c0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73  TDCALL sqlite3_s
2b2d0 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
2b2e0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2b2f0 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
2b300 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
2b310 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
2b320 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
2b330 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
2b340 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
2b350 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
2b360 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2b370 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2b380 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
2b390 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
2b3a0 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
2b3b0 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
2b3c0 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
2b3d0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
2b3e0 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
2b3f0 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
2b400 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
2b410 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
2b420 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
2b430 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
2b440 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2b450 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
2b460 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
2b470 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
2b480 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
2b490 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
2b4a0 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
2b4b0 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
2b4c0 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2b4d0 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
2b4e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2b4f0 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
2b500 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
2b510 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
2b520 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
2b530 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b540 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
2b550 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
2b560 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
2b570 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
2b580 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
2b590 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
2b5a0 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
2b5b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
2b5c0 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22  *.** The terms "
2b5d0 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22  protected" and "
2b5e0 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66  unprotected" ref
2b5f0 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72  er to whether or
2b600 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20   not.** a mutex 
2b610 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74  is held.  An int
2b620 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68  ernal mutex is h
2b630 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63  eld for a protec
2b640 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2b650 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20  alue object but 
2b660 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64  no mutex is held
2b670 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63   for an unprotec
2b680 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2b690 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66  alue object.  If
2b6a0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
2b6b0 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65  led to be single
2b6c0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69  -threaded.** (wi
2b6d0 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  th [SQLITE_THREA
2b6e0 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74  DSAFE=0] and wit
2b6f0 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61  h [sqlite3_threa
2b700 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69  dsafe()] returni
2b710 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53  ng 0).** or if S
2b720 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20  QLite is run in 
2b730 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d  one of reduced m
2b740 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b  utex modes .** [
2b750 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2b760 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b  NGLETHREAD] or [
2b770 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2b780 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68  LTITHREAD].** th
2b790 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64  en there is no d
2b7a0 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
2b7b0 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
2b7c0 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
2b7d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2b7e0 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63  jects and they c
2b7f0 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72  an be used inter
2b800 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77  changeably.  How
2b810 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78  ever,.** for max
2b820 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62  imum code portab
2b830 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f  ility it is reco
2b840 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
2b850 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69  lications.** sti
2b860 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  ll make the dist
2b870 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  inction between 
2b880 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e  protected and un
2b890 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2b8a0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2b8b0 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74  ts even when not
2b8c0 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72   strictly requir
2b8d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2b8e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2b8f0 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61  ects that are pa
2b900 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65  ssed as paramete
2b910 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69  rs into the.** i
2b920 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2b930 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2b940 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2b950 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74  ons] are protect
2b960 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
2b970 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2b980 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2b990 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2b9a0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72  value()] is unpr
2b9b0 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72  otected..** Unpr
2b9c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b9d0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61  value objects ma
2b9e0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
2b9f0 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ith.** [sqlite3_
2ba00 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20  result_value()] 
2ba10 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2ba20 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54  d_value()]..** T
2ba30 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2ba40 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  e_blob | sqlite3
2ba50 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66  _value_type()] f
2ba60 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65  amily of.** inte
2ba70 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70  rfaces require p
2ba80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ba90 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a  _value objects..
2baa0 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
2bab0 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61  t Mem sqlite3_va
2bac0 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lue;../*.** CAPI
2bad0 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69  3REF: SQL Functi
2bae0 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63  on Context Objec
2baf0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74  t.**.** The cont
2bb00 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20  ext in which an 
2bb10 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65  SQL function exe
2bb20 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20  cutes is stored 
2bb30 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  in an.** sqlite3
2bb40 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e  _context object.
2bb50 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20    ^A pointer to 
2bb60 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  an sqlite3_conte
2bb70 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20  xt object.** is 
2bb80 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72  always first par
2bb90 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69  ameter to [appli
2bba0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2bbb0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  QL functions]..*
2bbc0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2bbd0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
2bbe0 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
2bbf0 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20  ation will pass 
2bc00 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  this.** pointer 
2bc10 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c  through into cal
2bc20 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72  ls to [sqlite3_r
2bc30 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69  esult_int | sqli
2bc40 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a  te3_result()],.*
2bc50 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65  * [sqlite3_aggre
2bc60 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c  gate_context()],
2bc70 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2bc80 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ata()],.** [sqli
2bc90 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
2bca0 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74  andle()], [sqlit
2bcb0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2bcc0 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71  ],.** and/or [sq
2bcd0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
2bce0 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  a()]..*/.typedef
2bcf0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
2bd00 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f  context sqlite3_
2bd10 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20  context;../*.** 
2bd20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e  CAPI3REF: Bindin
2bd30 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70  g Values To Prep
2bd40 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a  ared Statements.
2bd50 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f  ** KEYWORDS: {ho
2bd60 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68  st parameter} {h
2bd70 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20  ost parameters} 
2bd80 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  {host parameter 
2bd90 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  name}.** KEYWORD
2bda0 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  S: {SQL paramete
2bdb0 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65  r} {SQL paramete
2bdc0 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62  rs} {parameter b
2bdd0 69 6e 64 69 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f  inding}.** METHO
2bde0 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
2bdf0 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
2be00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
2be10 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
2be20 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2be30 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
2be40 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
2be50 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
2be60 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
2be70 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
2be80 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
2be90 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
2bea0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2beb0 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
2bec0 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
2bed0 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
2bee0 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
2bef0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
2bf00 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
2bf10 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
2bf20 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
2bf30 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
2bf40 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
2bf50 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
2bf60 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
2bf70 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
2bf80 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
2bf90 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
2bfa0 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
2bfb0 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
2bfc0 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
2bfd0 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
2bfe0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
2bff0 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
2c000 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
2c010 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2c020 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
2c030 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2c040 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
2c050 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
2c060 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
2c070 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
2c080 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
2c090 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2c0a0 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
2c0b0 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
2c0c0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2c0d0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
2c0e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
2c0f0 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
2c100 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
2c110 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
2c120 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
2c130 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
2c140 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
2c150 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
2c160 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
2c170 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
2c180 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
2c190 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
2c1a0 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
2c1b0 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
2c1c0 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
2c1d0 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
2c1e0 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
2c1f0 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
2c200 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2c210 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
2c220 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
2c230 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
2c240 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
2c250 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2c260 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
2c270 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
2c280 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
2c290 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
2c2a0 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
2c2b0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
2c2c0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
2c2d0 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
2c2e0 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
2c2f0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
2c300 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
2c310 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
2c320 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eter..** ^If the
2c330 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2c340 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2c350 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
2c360 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2c370 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
2c380 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20  ind_blob() is a 
2c390 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
2c3a0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  n the fourth par
2c3b0 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e  ameter.** is ign
2c3c0 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64  ored and the end
2c3d0 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73   result is the s
2c3e0 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62  ame as sqlite3_b
2c3f0 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a  ind_null()..**.*
2c400 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
2c410 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
2c420 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
2c430 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
2c440 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2c450 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
2c460 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
2c470 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
2c480 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2c490 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
2c4a0 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
2c4b0 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
2c4c0 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
2c4d0 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
2c4e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2c4f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2c500 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
2c510 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69  nd_text16().** i
2c520 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
2c530 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
2c540 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
2c550 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2c560 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
2c570 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
2c580 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  tor..** If the f
2c590 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2c5a0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2c5b0 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69  blob() is negati
2c5c0 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ve, then.** the 
2c5d0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2c5e0 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e  fined..** If a n
2c5f0 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
2c600 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2c610 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
2c620 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
2c630 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
2c640 6e 64 5f 74 65 78 74 31 36 28 29 20 6f 72 20 73  nd_text16() or s
2c650 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2c660 36 34 28 29 20 74 68 65 6e 0a 2a 2a 20 74 68 61  64() then.** tha
2c670 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
2c680 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66   be the byte off
2c690 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65  set.** where the
2c6a0 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20   NUL terminator 
2c6b0 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75  would occur assu
2c6c0 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20  ming the string 
2c6d0 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d  were NUL.** term
2c6e0 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
2c6f0 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
2c700 63 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66  ccur at byte off
2c710 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a  sets less than .
2c720 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ** the value of 
2c730 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2c740 65 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65  eter then the re
2c750 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76  sulting string v
2c760 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  alue will.** con
2c770 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55  tain embedded NU
2c780 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20  Ls.  The result 
2c790 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69  of expressions i
2c7a0 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73  nvolving strings
2c7b0 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65  .** with embedde
2c7c0 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
2c7d0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2c7e0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74  fifth argument t
2c7f0 6f 20 74 68 65 20 42 4c 4f 42 20 61 6e 64 20 73  o the BLOB and s
2c800 74 72 69 6e 67 20 62 69 6e 64 69 6e 67 20 69 6e  tring binding in
2c810 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 61  terfaces.** is a
2c820 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
2c830 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
2c840 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
2c850 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
2c860 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
2c870 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65  ith it.  ^The de
2c880 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
2c890 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65  ed.** to dispose
2c8a0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
2c8b0 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74  string even if t
2c8c0 68 65 20 63 61 6c 6c 20 74 6f 20 62 69 6e 64 20  he call to bind 
2c8d0 41 50 49 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49  API fails..** ^I
2c8e0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
2c8f0 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
2c900 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
2c910 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
2c920 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
2c930 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
2c940 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
2c950 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
2c960 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
2c970 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
2c980 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
2c990 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2c9a0 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
2c9b0 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
2c9c0 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
2c9d0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
2c9e0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
2c9f0 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
2ca00 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
2ca10 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2ca20 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
2ca30 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
2ca40 20 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20   sixth argument 
2ca50 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2ca60 74 65 78 74 36 34 28 29 20 6d 75 73 74 20 62 65  text64() must be
2ca70 20 6f 6e 65 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49   one of.** [SQLI
2ca80 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54  TE_UTF8], [SQLIT
2ca90 45 5f 55 54 46 31 36 5d 2c 20 5b 53 51 4c 49 54  E_UTF16], [SQLIT
2caa0 45 5f 55 54 46 31 36 42 45 5d 2c 20 6f 72 20 5b  E_UTF16BE], or [
2cab0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 0a  SQLITE_UTF16LE].
2cac0 2a 2a 20 74 6f 20 73 70 65 63 69 66 79 20 74 68  ** to specify th
2cad0 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 74 68  e encoding of th
2cae0 65 20 74 65 78 74 20 69 6e 20 74 68 65 20 74 68  e text in the th
2caf0 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ird parameter.  
2cb00 49 66 0a 2a 2a 20 74 68 65 20 73 69 78 74 68 20  If.** the sixth 
2cb10 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
2cb20 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2cb30 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20  ) is not one of 
2cb40 74 68 65 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 76  the.** allowed v
2cb50 61 6c 75 65 73 20 73 68 6f 77 6e 20 61 62 6f 76  alues shown abov
2cb60 65 2c 20 6f 72 20 69 66 20 74 68 65 20 74 65 78  e, or if the tex
2cb70 74 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69  t encoding is di
2cb80 66 66 65 72 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20  fferent.** from 
2cb90 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
2cba0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 73 69  cified by the si
2cbb0 78 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 74  xth parameter, t
2cbc0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2cbd0 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
2cbe0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2cbf0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2cc00 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e  ob() routine bin
2cc10 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e  ds a BLOB of len
2cc20 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73  gth N that.** is
2cc30 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72   filled with zer
2cc40 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f  oes.  ^A zeroblo
2cc50 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61  b uses a fixed a
2cc60 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a  mount of memory.
2cc70 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65  ** (just an inte
2cc80 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20  ger to hold its 
2cc90 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69  size) while it i
2cca0 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65  s being processe
2ccb0 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20  d..** Zeroblobs 
2ccc0 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
2ccd0 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f  serve as placeho
2cce0 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20  lders for BLOBs 
2ccf0 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  whose.** content
2cd00 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65   is later writte
2cd10 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
2cd20 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
2cd30 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
2cd40 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a   I/O] routines..
2cd50 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76  ** ^A negative v
2cd60 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72  alue for the zer
2cd70 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e  oblob results in
2cd80 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
2cd90 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  LOB..**.** ^If a
2cda0 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ny of the sqlite
2cdb0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2cdc0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77  nes are called w
2cdd0 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
2cde0 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70  er.** for the [p
2cdf0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ce00 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65  t] or with a pre
2ce10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2ce20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71  for which.** [sq
2ce30 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2ce40 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f  s been called mo
2ce50 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e  re recently than
2ce60 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ce70 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  )],.** then the 
2ce80 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e  call will return
2ce90 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2cea0 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65  .  If any sqlite
2ceb0 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75  3_bind_().** rou
2cec0 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61  tine is passed a
2ced0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2cee0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62  ment] that has b
2cef0 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74  een finalized, t
2cf00 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20  he.** result is 
2cf10 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
2cf20 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a  obably harmful..
2cf30 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20  **.** ^Bindings 
2cf40 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20  are not cleared 
2cf50 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
2cf60 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65  reset()] routine
2cf70 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61  ..** ^Unbound pa
2cf80 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74  rameters are int
2cf90 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c  erpreted as NULL
2cfa0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2cfb0 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74  ite3_bind_* rout
2cfc0 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c  ines return [SQL
2cfd0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
2cfe0 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72  ss or an.** [err
2cff0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74  or code] if anyt
2d000 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e  hing goes wrong.
2d010 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f  .** ^[SQLITE_TOO
2d020 42 49 47 5d 20 6d 69 67 68 74 20 62 65 20 72 65  BIG] might be re
2d030 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 73 69  turned if the si
2d040 7a 65 20 6f 66 20 61 20 73 74 72 69 6e 67 20 6f  ze of a string o
2d050 72 20 42 4c 4f 42 0a 2a 2a 20 65 78 63 65 65 64  r BLOB.** exceed
2d060 73 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64  s limits imposed
2d070 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
2d080 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
2d090 54 5f 4c 45 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a  T_LENGTH]) or.**
2d0a0 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e   [SQLITE_MAX_LEN
2d0b0 47 54 48 5d 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  GTH]..** ^[SQLIT
2d0c0 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
2d0d0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
2d0e0 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
2d0f0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
2d100 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
2d110 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2d120 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
2d130 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2d140 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2d150 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2d160 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2d170 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2d180 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
2d190 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2d1a0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
2d1b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2d1c0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2d1d0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73  ite3_bind_blob(s
2d1e0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2d1f0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2d200 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76  int n, void(*)(v
2d210 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2d220 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2d230 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2d240 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69 74 65  nd_blob64(sqlite
2d250 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2d260 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c 69 74  nst void*, sqlit
2d270 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20 20 20  e3_uint64,.     
2d280 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2d290 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a     void(*)(void*
2d2a0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
2d2b0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2d2c0 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  L sqlite3_bind_d
2d2d0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
2d2e0 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
2d2f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2d300 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2d310 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e   sqlite3_bind_in
2d320 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2d330 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49   int, int);.SQLI
2d340 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2d350 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2d360 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
2d370 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2d380 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
2d390 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2d3a0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2d3b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
2d3c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d3d0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2d3e0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
2d3f0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  ALL sqlite3_bind
2d400 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2d410 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  mt*,int,const ch
2d420 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28  ar*,int,void(*)(
2d430 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
2d440 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2d450 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2d460 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ind_text16(sqlit
2d470 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2d480 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
2d490 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29   void(*)(void*))
2d4a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2d4b0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2d4c0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2d4d0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
2d4e0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68  *, int, const ch
2d4f0 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 75 69 6e  ar*, sqlite3_uin
2d500 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20 20 20  t64,.           
2d510 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76 6f                vo
2d520 69 64 28 2a 29 28 76 6f 69 64 2a 29 2c 20 75 6e  id(*)(void*), un
2d530 73 69 67 6e 65 64 20 63 68 61 72 20 65 6e 63 6f  signed char enco
2d540 64 69 6e 67 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ding);.SQLITE_AP
2d550 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
2d560 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e  CALL sqlite3_bin
2d570 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
2d580 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2d590 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
2d5a0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2d5b0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2d5c0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2d5d0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
2d5e0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
2d5f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d600 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
2d610 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  L Parameters.** 
2d620 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2d630 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  stmt.**.** ^This
2d640 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2d650 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
2d660 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
2d670 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
2d680 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2d690 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
2d6a0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
2d6b0 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
2d6c0 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
2d6d0 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
2d6e0 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
2d6f0 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
2d700 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
2d710 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
2d720 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2d730 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
2d740 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
2d750 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
2d760 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
2d770 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
2d780 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
2d790 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
2d7a0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
2d7b0 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
2d7c0 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
2d7d0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
2d7e0 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
2d7f0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
2d800 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
2d810 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
2d820 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
2d830 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
2d840 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
2d850 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
2d860 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2d870 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2d880 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2d890 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2d8a0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2d8b0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2d8c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2d8d0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2d8e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2d8f0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2d900 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2d910 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69  meter_count(sqli
2d920 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
2d930 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2d940 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61  e Of A Host Para
2d950 6d 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a  meter.** METHOD:
2d960 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2d970 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2d980 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2d990 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
2d9a0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
2d9b0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
2d9c0 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
2d9d0 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
2d9e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d9f0 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
2da00 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2da10 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
2da20 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2da30 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
2da40 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
2da50 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
2da60 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2da70 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2da80 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
2da90 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2daa0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
2dab0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
2dac0 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
2dad0 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
2dae0 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
2daf0 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
2db00 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
2db10 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
2db20 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
2db30 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
2db40 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
2db50 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
2db60 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
2db70 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
2db80 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
2db90 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2dba0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
2dbb0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
2dbc0 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
2dbd0 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
2dbe0 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
2dbf0 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
2dc00 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
2dc10 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
2dc20 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
2dc30 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
2dc40 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
2dc50 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
2dc60 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
2dc70 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
2dc80 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
2dc90 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2dca0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
2dcb0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2dcc0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2dcd0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2dce0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2dcf0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2dd00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2dd10 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2dd20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2dd30 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2dd40 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
2dd50 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2dd60 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
2dd70 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  L sqlite3_bind_p
2dd80 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
2dd90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2dda0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ddb0 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
2ddc0 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
2ddd0 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 20 4d 45  Given Name.** ME
2dde0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2ddf0 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  mt.**.** ^Return
2de00 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
2de10 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
2de20 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
2de30 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
2de40 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
2de50 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
2de60 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
2de70 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
2de80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2de90 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2dea0 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
2deb0 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
2dec0 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
2ded0 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
2dee0 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
2def0 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
2df00 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
2df10 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
2df20 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
2df30 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
2df40 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
2df50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
2df60 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2df70 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2df80 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2df90 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2dfa0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2dfb0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2dfc0 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2dfd0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2dfe0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2dff0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2e000 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2e010 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2e020 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71 6c  ameter_index(sql
2e030 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73  ite3_stmt*, cons
2e040 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
2e050 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e060 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64 69   Reset All Bindi
2e070 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72 65  ngs On A Prepare
2e080 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4d  d Statement.** M
2e090 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2e0a0 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72  tmt.**.** ^Contr
2e0b0 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69  ary to the intui
2e0c0 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73  tion of many, [s
2e0d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2e0e0 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a  does not reset.*
2e0f0 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
2e100 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69  ind_blob | bindi
2e110 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61  ngs] on a [prepa
2e120 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2e130 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75  ** ^Use this rou
2e140 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c  tine to reset al
2e150 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  l host parameter
2e160 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51  s to NULL..*/.SQ
2e170 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2e180 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2e190 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2e1a0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2e1b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2e1c0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
2e1d0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
2e1e0 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
2e1f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2e200 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2e210 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2e220 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2e230 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
2e240 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2e250 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68   statement]. ^Th
2e260 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
2e270 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20 69 73  ns 0 if pStmt is
2e280 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65   an SQL.** state
2e290 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73 20 6e  ment that does n
2e2a0 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61 20 28  ot return data (
2e2b0 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b  for example an [
2e2c0 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20  UPDATE])..**.** 
2e2d0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2e2e0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
2e2f0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2e300 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2e310 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2e320 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2e330 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2e340 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2e350 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
2e360 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20 4d 45  Result Set.** ME
2e370 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74  THOD: sqlite3_st
2e380 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  mt.**.** ^These 
2e390 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2e3a0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
2e3b0 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
2e3c0 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
2e3d0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
2e3e0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
2e3f0 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
2e400 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2e410 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
2e420 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2e430 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
2e440 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
2e450 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
2e460 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2e470 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
2e480 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2e490 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
2e4a0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2e4b0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2e4c0 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
2e4d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2e4e0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
2e4f0 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
2e500 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
2e510 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2e520 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
2e530 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
2e540 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
2e550 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
2e560 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2e570 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
2e580 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
2e590 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
2e5a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2e5b0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
2e5c0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2e5d0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2e5e0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2e5f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2e600 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2e610 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2e620 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2e630 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2e640 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2e650 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
2e660 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2e670 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
2e680 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2e690 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
2e6a0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
2e6b0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
2e6c0 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
2e6d0 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
2e6e0 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
2e6f0 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
2e700 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
2e710 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
2e720 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
2e730 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
2e740 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2e750 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2e760 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
2e770 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
2e780 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
2e790 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
2e7a0 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
2e7b0 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
2e7c0 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
2e7d0 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
2e7e0 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
2e7f0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
2e800 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
2e810 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
2e820 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
2e830 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
2e840 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ext..*/.SQLITE_A
2e850 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
2e860 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2e870 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2e880 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2e890 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f   int N);.SQLITE_
2e8a0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2e8b0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2e8c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2e8d0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2e8e0 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a  t*, int N);../*.
2e8f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75  ** CAPI3REF: Sou
2e900 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41  rce Of Data In A
2e910 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2e920 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2e930 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2e940 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
2e950 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
2e960 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
2e970 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2e980 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
2e990 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
2e9a0 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
2e9b0 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
2e9c0 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
2e9d0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
2e9e0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
2e9f0 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
2ea00 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
2ea10 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
2ea20 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
2ea30 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
2ea40 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
2ea50 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
2ea60 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
2ea70 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
2ea80 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
2ea90 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
2eaa0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
2eab0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
2eac0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
2ead0 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
2eae0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2eaf0 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
2eb00 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
2eb10 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
2eb20 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
2eb30 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2eb40 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2eb50 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2eb60 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2eb70 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2eb80 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2eb90 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2eba0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2ebb0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2ebc0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
2ebd0 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
2ebe0 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
2ebf0 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
2ec00 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
2ec10 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
2ec20 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
2ec30 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
2ec40 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
2ec50 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2ec60 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
2ec70 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2ec80 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
2ec90 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
2eca0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ecb0 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
2ecc0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
2ecd0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2ece0 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
2ecf0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2ed00 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
2ed10 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
2ed20 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
2ed30 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
2ed40 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
2ed50 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
2ed60 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
2ed70 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
2ed80 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
2ed90 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
2eda0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
2edb0 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
2edc0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
2edd0 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
2ede0 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
2edf0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2ee00 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
2ee10 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
2ee20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
2ee30 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
2ee40 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2ee50 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
2ee60 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
2ee70 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2ee80 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
2ee90 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2eea0 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
2eeb0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
2eec0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
2eed0 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
2eee0 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
2eef0 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
2ef00 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
2ef10 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
2ef20 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
2ef30 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
2ef40 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
2ef50 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2ef60 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
2ef70 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
2ef80 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2ef90 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2efa0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2efb0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2efc0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2efd0 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2efe0 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
2eff0 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2f000 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2f010 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2f020 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
2f030 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
2f040 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2f050 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
2f060 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2f070 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2f080 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
2f090 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
2f0a0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2f0b0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2f0c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2f0d0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2f0e0 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
2f0f0 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
2f100 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2f110 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f120 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
2f130 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
2f140 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2f150 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2f160 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51  undefined..*/.SQ
2f170 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2f180 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
2f190 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2f1a0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2f1b0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2f1c0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2f1d0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
2f1e0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2f1f0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2f200 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  se_name16(sqlite
2f210 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2f220 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2f230 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
2f240 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2f250 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
2f260 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2f270 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2f280 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
2f290 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
2f2a0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2f2b0 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2f2c0 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2f2d0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 53  PI const char *S
2f2e0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2f2f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2f300 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
2f310 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2f320 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2f330 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
2f340 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  LL sqlite3_colum
2f350 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
2f360 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2f370 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2f380 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
2f390 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
2f3a0 79 20 52 65 73 75 6c 74 0a 2a 2a 20 4d 45 54 48  y Result.** METH
2f3b0 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
2f3c0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72  .**.** ^(The fir
2f3d0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2f3e0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2f3f0 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68  ement]..** If th
2f400 69 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  is statement is 
2f410 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
2f420 6d 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68  ment and the Nth
2f430 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a   column of the.*
2f440 2a 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c  * returned resul
2f450 74 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53  t set of that [S
2f460 45 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c  ELECT] is a tabl
2f470 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e  e column (not an
2f480 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f  .** expression o
2f490 72 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e  r subquery) then
2f4a0 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2f4b0 70 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a  pe of the table.
2f4c0 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74  ** column is ret
2f4d0 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68  urned.)^  ^If th
2f4e0 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2f4f0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69  the result set i
2f500 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  s an.** expressi
2f510 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20  on or subquery, 
2f520 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  then a NULL poin
2f530 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ter is returned.
2f540 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
2f550 64 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61  d string is alwa
2f560 79 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  ys UTF-8 encoded
2f570 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78  ..**.** ^(For ex
2f580 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65  ample, given the
2f590 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
2f5a0 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54  :.**.** CREATE T
2f5b0 41 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41  ABLE t1(c1 VARIA
2f5c0 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74  NT);.**.** and t
2f5d0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61  he following sta
2f5e0 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d  tement to be com
2f5f0 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c  piled:.**.** SEL
2f600 45 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46  ECT c1 + 1, c1 F
2f610 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68  ROM t1;.**.** th
2f620 69 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64  is routine would
2f630 20 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69   return the stri
2f640 6e 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72  ng "VARIANT" for
2f650 20 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75   the second resu
2f660 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d  lt.** column (i=
2f670 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20  =1), and a NULL 
2f680 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20  pointer for the 
2f690 66 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c  first result col
2f6a0 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a  umn (i==0).)^.**
2f6b0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
2f6c0 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d   dynamic run-tim
2f6d0 65 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a  e typing.  ^So j
2f6e0 75 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f  ust because a co
2f6f0 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61  lumn.** is decla
2f700 72 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61  red to contain a
2f710 20 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65   particular type
2f720 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74   does not mean t
2f730 68 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20  hat the.** data 
2f740 73 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63  stored in that c
2f750 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20  olumn is of the 
2f760 64 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20  declared type.  
2f770 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72  SQLite is.** str
2f780 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74  ongly typed, but
2f790 20 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64   the typing is d
2f7a0 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69  ynamic not stati
2f7b0 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20  c.  ^Type.** is 
2f7c0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2f7d0 69 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65  individual value
2f7e0 73 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20  s, not with the 
2f7f0 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73  containers.** us
2f800 65 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65  ed to hold those
2f810 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49   values..*/.SQLI
2f820 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2f830 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  r *SQLITE_STDCAL
2f840 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2f850 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
2f860 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
2f870 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2f880 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
2f890 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
2f8a0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
2f8b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2f8c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2f8d0 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
2f8e0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  QL Statement.** 
2f8f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2f900 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72  stmt.**.** After
2f910 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2f920 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e  tement] has been
2f930 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2f940 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74  either.** [sqlit
2f950 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2f960 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2f970 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2f980 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63  one of the legac
2f990 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  y.** interfaces 
2f9a0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f9b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2f9c0 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68  prepare16()], th
2f9d0 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d  is function.** m
2f9e0 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e  ust be called on
2f9f0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20  e or more times 
2fa00 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20  to evaluate the 
2fa10 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a  statement..**.**
2fa20 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20   The details of 
2fa30 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
2fa40 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2fa50 28 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70  () interface dep
2fa60 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65  end.** on whethe
2fa70 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  r the statement 
2fa80 77 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69  was prepared usi
2fa90 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32  ng the newer "v2
2faa0 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b  " interface.** [
2fab0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2fac0 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
2fad0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2fae0 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20  )] or the older 
2faf0 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2fb00 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ace [sqlite3_pre
2fb10 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2fb20 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2fb30 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ].  The use of t
2fb40 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69  he.** new "v2" i
2fb50 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2fb60 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20  mmended for new 
2fb70 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74  applications but
2fb80 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2fb90 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f  nterface will co
2fba0 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70  ntinue to be sup
2fbb0 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ported..**.** ^I
2fbc0 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2fbd0 65 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75  erface, the retu
2fbe0 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65  rn value will be
2fbf0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
2fc00 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  BUSY],.** [SQLIT
2fc10 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  E_DONE], [SQLITE
2fc20 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45  _ROW], [SQLITE_E
2fc30 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  RROR], or [SQLIT
2fc40 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57  E_MISUSE]..** ^W
2fc50 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2fc60 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74  erface, any of t
2fc70 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74  he other [result
2fc80 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65   codes] or.** [e
2fc90 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
2fca0 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72  odes] might be r
2fcb0 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e  eturned as well.
2fcc0 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2fcd0 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74  BUSY] means that
2fce0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e   the database en
2fcf0 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20  gine was unable 
2fd00 74 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a  to acquire the.*
2fd10 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73  * database locks
2fd20 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20   it needs to do 
2fd30 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68  its job.  ^If th
2fd40 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2fd50 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20   [COMMIT].** or 
2fd60 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f  occurs outside o
2fd70 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72  f an explicit tr
2fd80 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20  ansaction, then 
2fd90 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68  you can retry th
2fda0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20  e.** statement. 
2fdb0 20 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   If the statemen
2fdc0 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d  t is not a [COMM
2fdd0 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77  IT] and occurs w
2fde0 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c  ithin an.** expl
2fdf0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2fe00 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64   then you should
2fe10 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72   rollback the tr
2fe20 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65  ansaction before
2fe30 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a  .** continuing..
2fe40 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44  **.** ^[SQLITE_D
2fe50 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ONE] means that 
2fe60 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2fe70 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75  s finished execu
2fe80 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66  ting.** successf
2fe90 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73  ully.  sqlite3_s
2fea0 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
2feb0 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
2fec0 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c   on this virtual
2fed0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68  .** machine with
2fee0 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e  out first callin
2fef0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2ff00 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
2ff10 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2ff20 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20  ine back to its 
2ff30 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a  initial state..*
2ff40 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c  *.** ^If the SQL
2ff50 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67   statement being
2ff60 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e   executed return
2ff70 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e  s any data, then
2ff80 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a   [SQLITE_ROW].**
2ff90 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63   is returned eac
2ffa0 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77  h time a new row
2ffb0 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64   of data is read
2ffc0 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67  y for processing
2ffd0 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65   by the.** calle
2ffe0 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61  r. The values ma
2fff0 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73  y be accessed us
30000 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20  ing the [column 
30010 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
30020 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  ]..** sqlite3_st
30030 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ep() is called a
30040 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65  gain to retrieve
30050 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66   the next row of
30060 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53   data..**.** ^[S
30070 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61  QLITE_ERROR] mea
30080 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69  ns that a run-ti
30090 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61  me error (such a
300a0 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a  s a constraint.*
300b0 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73  * violation) has
300c0 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69   occurred.  sqli
300d0 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
300e0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
300f0 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20  again on.** the 
30100 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61  VM. More informa
30110 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e  tion may be foun
30120 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  d by calling [sq
30130 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
30140 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65  .** ^With the le
30150 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
30160 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  a more specific 
30170 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20  error code (for 
30180 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c  example,.** [SQL
30190 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20  ITE_INTERRUPT], 
301a0 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c  [SQLITE_SCHEMA],
301b0 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54   [SQLITE_CORRUPT
301c0 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29  ], and so forth)
301d0 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69  .** can be obtai
301e0 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  ned by calling [
301f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30200 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   on the.** [prep
30210 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
30220 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69    ^In the "v2" i
30230 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65  nterface,.** the
30240 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
30250 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74  rror code is ret
30260 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62  urned directly b
30270 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
30280 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ..**.** [SQLITE_
30290 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68  MISUSE] means th
302a0 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74  at the this rout
302b0 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69  ine was called i
302c0 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a  nappropriately..
302d0 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61  ** Perhaps it wa
302e0 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70  s called on a [p
302f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
30300 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61  t] that has.** a
30310 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c  lready been [sql
30320 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
30330 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e  finalized] or on
30340 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a   one that had.**
30350 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
30360 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52  rned [SQLITE_ERR
30370 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OR] or [SQLITE_D
30380 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75  ONE].  Or it cou
30390 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73  ld.** be the cas
303a0 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20  e that the same 
303b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
303c0 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65  ion is being use
303d0 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d  d by two or.** m
303e0 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74  ore threads at t
303f0 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69  he same moment i
30400 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f  n time..**.** Fo
30410 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f  r all versions o
30420 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61  f SQLite up to a
30430 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36  nd including 3.6
30440 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f  .23.1, a call to
30450 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
30460 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72  et()] was requir
30470 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
30480 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64  _step() returned
30490 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68   anything.** oth
304a0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
304b0 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20  ROW] before any 
304c0 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
304d0 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69  ation of.** sqli
304e0 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69  te3_step().  Fai
304f0 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68  lure to reset th
30500 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
30510 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b  ment using .** [
30520 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
30530 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   would result in
30540 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   an [SQLITE_MISU
30550 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a  SE] return from.
30560 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
30570 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65  ).  But after ve
30580 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20  rsion 3.6.23.1, 
30590 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62  sqlite3_step() b
305a0 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20  egan.** calling 
305b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
305c0 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  ] automatically 
305d0 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74  in this circumst
305e0 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74  ance rather.** t
305f0 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53  han returning [S
30600 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
30610 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73  This is not cons
30620 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69  idered a compati
30630 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20  bility.** break 
30640 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c  because any appl
30650 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65  ication that eve
30660 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51  r receives an SQ
30670 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f  LITE_MISUSE erro
30680 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62  r.** is broken b
30690 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  y definition.  T
306a0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
306b0 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69  AUTORESET] compi
306c0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a  le-time option.*
306d0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
306e0 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67   restore the leg
306f0 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  acy behavior..**
30700 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74  .** <b>Goofy Int
30710 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62  erface Alert:</b
30720 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20  > In the legacy 
30730 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73  interface, the s
30740 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a  qlite3_step().**
30750 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75   API always retu
30760 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72  rns a generic er
30770 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54  ror code, [SQLIT
30780 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77  E_ERROR], follow
30790 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72  ing any.** error
307a0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
307b0 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53  ITE_BUSY] and [S
307c0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
307d0 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a  You must call.**
307e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
307f0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
30800 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72  inalize()] in or
30810 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20  der to find one 
30820 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  of the.** specif
30830 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
30840 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73   that better des
30850 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72  cribes the error
30860 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68  ..** We admit th
30870 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f  at this is a goo
30880 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20  fy design.  The 
30890 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e  problem has been
308a0 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74   fixed.** with t
308b0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
308c0 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61  e.  If you prepa
308d0 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53  re all of your S
308e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
308f0 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
30900 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
30910 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
30920 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
30930 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74   instead.** of t
30940 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74  he legacy [sqlit
30950 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e  e3_prepare()] an
30960 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
30970 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63  re16()] interfac
30980 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  es,.** then the 
30990 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65  more specific [e
309a0 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20  rror codes] are 
309b0 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
309c0 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  y.** by sqlite3_
309d0 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65  step().  The use
309e0 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74   of the "v2" int
309f0 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d  erface is recomm
30a00 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ended..*/.SQLITE
30a10 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
30a20 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
30a30 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
30a40 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
30a50 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
30a60 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
30a70 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult set.** METHO
30a80 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
30a90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30aa0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
30ab0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
30ac0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
30ad0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
30ae0 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
30af0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
30b00 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
30b10 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
30b20 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
30b30 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
30b40 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
30b50 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
30b60 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
30b70 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
30b80 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
30b90 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
30ba0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
30bb0 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
30bc0 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
30bd0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
30be0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
30bf0 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
30c00 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
30c10 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
30c20 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
30c30 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
30c40 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
30c50 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
30c60 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
30c70 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
30c80 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
30c90 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
30ca0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
30cb0 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
30cc0 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
30cd0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
30ce0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
30cf0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
30d00 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
30d10 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
30d20 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
30d30 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
30d40 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
30d50 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
30d60 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
30d70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
30d80 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
30d90 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
30da0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
30db0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
30dc0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
30dd0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
30de0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
30df0 4c 4c 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  LL sqlite3_data_
30e00 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
30e10 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
30e20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
30e30 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
30e40 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
30e50 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
30e60 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
30e70 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
30e80 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
30e90 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
30ea0 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
30eb0 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
30ec0 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
30ed0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
30ee0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
30ef0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
30f00 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
30f10 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
30f20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
30f30 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
30f40 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
30f50 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
30f60 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
30f70 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
30f80 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
30f90 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
30fa0 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
30fb0 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
30fc0 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
30fd0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
30fe0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
30ff0 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
31000 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
31010 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
31020 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
31030 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
31040 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
31050 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
31060 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
31070 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
31080 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
31090 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
310a0 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
310b0 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
310c0 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
310d0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
310e0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
310f0 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
31100 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
31110 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
31120 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31130 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
31140 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
31150 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
31160 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
31170 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  s}.** METHOD: sq
31180 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
31190 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
311a0 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
311b0 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e   set" interface.
311c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
311d0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
311e0 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
311f0 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
31200 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
31210 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
31220 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
31230 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
31240 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
31250 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
31260 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
31270 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
31280 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
31290 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
312a0 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
312b0 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
312c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
312d0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
312e0 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
312f0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
31300 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
31310 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
31320 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
31330 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
31340 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
31350 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
31360 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
31370 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
31380 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
31390 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
313a0 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
313b0 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
313c0 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
313d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
313e0 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
313f0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
31400 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
31410 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
31420 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
31430 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
31440 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
31450 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
31460 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
31470 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
31480 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
31490 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
314a0 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
314b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
314c0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
314d0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
314e0 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
314f0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
31500 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
31510 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
31520 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
31530 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
31540 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
31550 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
31560 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
31570 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
31580 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
31590 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
315a0 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
315b0 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
315c0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
315d0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
315e0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
315f0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
31600 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
31610 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
31620 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
31630 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
31640 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
31650 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
31660 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
31670 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
31680 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
31690 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
316a0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
316b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
316c0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
316d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
316e0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
316f0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
31700 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
31710 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
31720 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
31730 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
31740 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
31750 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
31760 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
31770 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
31780 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
31790 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
317a0 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
317b0 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
317c0 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
317d0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
317e0 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
317f0 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
31800 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
31810 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
31820 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
31830 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
31840 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
31850 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
31860 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31870 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
31880 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
31890 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
318a0 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
318b0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
318c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
318d0 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
318e0 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
318f0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
31900 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
31910 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
31920 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
31930 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31940 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
31950 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
31960 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
31970 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
31980 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
31990 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
319a0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
319b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
319c0 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
319d0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
319e0 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
319f0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
31a00 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
31a10 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
31a20 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
31a30 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
31a40 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
31a50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
31a60 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
31a70 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
31a80 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
31a90 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
31aa0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
31ab0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
31ac0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
31ad0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
31ae0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
31af0 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
31b00 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
31b10 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
31b20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
31b30 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
31b40 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31b50 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
31b60 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
31b70 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
31b80 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
31b90 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
31ba0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
31bb0 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
31bc0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
31bd0 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
31be0 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
31bf0 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
31c00 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
31c10 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
31c20 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
31c30 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
31c40 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
31c50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31c60 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
31c70 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
31c80 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
31c90 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
31ca0 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
31cb0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
31cc0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
31cd0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
31ce0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
31cf0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
31d00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31d10 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
31d20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
31d30 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
31d40 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
31d50 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
31d60 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
31d70 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
31d80 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
31d90 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
31da0 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
31db0 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
31dc0 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
31dd0 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
31de0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
31df0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
31e00 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
31e10 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
31e20 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
31e30 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
31e40 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
31e50 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
31e60 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
31e70 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
31e80 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
31e90 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
31ea0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
31eb0 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
31ec0 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
31ed0 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
31ee0 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
31ef0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
31f00 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
31f10 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
31f20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
31f30 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
31f40 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
31f50 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
31f60 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
31f70 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
31f80 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
31f90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31fa0 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
31fb0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
31fc0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
31fd0 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
31fe0 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
31ff0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
32000 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
32010 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
32020 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
32030 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
32040 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
32050 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
32060 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
32070 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
32080 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
32090 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
320a0 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
320b0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
320c0 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
320d0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
320e0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
320f0 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
32100 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
32110 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
32120 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
32130 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
32140 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
32150 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
32160 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
32170 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
32180 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
32190 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
321a0 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
321b0 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
321c0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
321d0 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
321e0 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
321f0 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
32200 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
32210 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
32220 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
32230 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
32240 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
32250 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
32260 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
32270 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
32280 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
32290 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
322a0 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
322b0 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
322c0 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
322d0 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
322e0 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
322f0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
32300 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
32310 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
32320 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
32330 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
32340 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
32350 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
32360 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  sult is a NULL p
32370 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  ointer.** <tr><t
32380 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
32390 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
323a0 52 65 73 75 6c 74 20 69 73 20 61 20 4e 55 4c 4c  Result is a NULL
323b0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
323c0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
323d0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
323e0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
323f0 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
32400 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
32410 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
32420 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
32430 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
32440 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
32450 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
32460 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
32470 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
32480 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
32490 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
324a0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
324b0 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45  [CAST] to INTEGE
324c0 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  R.** <tr><td>  F
324d0 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45  LOAT   <td>   TE
324e0 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49  XT    <td> ASCII
324f0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
32500 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  e float.** <tr><
32510 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
32520 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
32530 20 5b 43 41 53 54 5d 20 74 6f 20 42 4c 4f 42 0a   [CAST] to BLOB.
32540 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
32550 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
32560 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
32570 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
32580 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
32590 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
325a0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
325b0 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
325c0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42  TEXT    <td>   B
325d0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63  LOB    <td> No c
325e0 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64  hange.** <tr><td
325f0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
32600 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
32610 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
32620 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
32630 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
32640 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
32650 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
32660 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
32670 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
32680 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
32690 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
326a0 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
326b0 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
326c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
326d0 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
326e0 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
326f0 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
32700 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
32710 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
32720 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
32730 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
32740 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
32750 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75  s its.** own equ
32760 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  ivalent internal
32770 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
32780 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
32790 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
327a0 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
327b0 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
327c0 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
327d0 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
327e0 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
327f0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
32800 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
32810 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
32820 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
32830 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
32840 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
32850 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
32860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32870 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
32880 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32890 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
328a0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
328b0 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
328c0 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
328d0 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
328e0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
328f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
32900 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
32910 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
32920 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
32930 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
32940 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
32950 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
32960 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
32970 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
32980 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
32990 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
329a0 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
329b0 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
329c0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
329d0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
329e0 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
329f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32a00 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
32a10 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
32a20 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
32a30 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
32a40 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
32a50 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
32a60 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
32a70 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
32a80 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
32a90 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
32aa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32ab0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
32ac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32ad0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
32ae0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
32af0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
32b00 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
32b10 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
32b20 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
32b30 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
32b40 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
32b50 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
32b60 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
32b70 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
32b80 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
32b90 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
32ba0 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
32bb0 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
32bc0 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
32bd0 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65  ointer reference
32be0 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  s will have been
32bf0 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
32c00 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
32c10 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
32c20 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
32c30 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
32c40 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68  but sometimes th
32c50 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f  ey.** are not po
32c60 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
32c70 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
32c80 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
32c90 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  alidated..**.** 
32ca0 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65  The safest and e
32cb0 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62  asiest to rememb
32cc0 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  er policy is to 
32cd0 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
32ce0 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
32cf0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
32d00 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
32d10 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
32d20 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
32d30 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
32d40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32d50 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
32d60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32d70 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
32d80 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
32d90 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
32da0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
32db0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
32dc0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
32dd0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
32de0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
32df0 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
32e00 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
32e10 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
32e20 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
32e30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32e40 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
32e50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
32e60 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
32e70 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
32e80 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
32e90 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
32ea0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
32eb0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
32ec0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
32ed0 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
32ee0 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
32ef0 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
32f00 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
32f10 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
32f20 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
32f30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
32f40 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
32f50 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
32f60 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
32f70 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
32f80 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
32f90 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
32fa0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
32fb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
32fc0 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  es()..**.** ^The
32fd0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
32fe0 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
32ff0 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
33000 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
33010 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
33020 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
33030 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
33040 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
33050 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
33060 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
33070 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65  called.  ^The me
33080 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
33090 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
330a0 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
330b0 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
330c0 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
330d0 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
330e0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
330f0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
33100 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
33110 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
33120 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
33130 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
33140 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
33150 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
33160 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
33170 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
33180 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
33190 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
331a0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
331b0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
331c0 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
331d0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
331e0 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
331f0 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
33200 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
33210 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
33220 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
33230 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
33240 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
33250 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
33260 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
33270 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ^.*/.SQLITE_API 
33280 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
33290 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
332a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
332b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
332c0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
332d0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
332e0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
332f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69  olumn_bytes(sqli
33300 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
33310 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
33320 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
33330 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
33340 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
33350 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
33360 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
33370 64 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f 53 54  double SQLITE_ST
33380 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
33390 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
333a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
333b0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
333c0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
333d0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ALL sqlite3_colu
333e0 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
333f0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
33400 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
33410 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45  te3_int64 SQLITE
33420 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
33430 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
33440 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
33450 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
33460 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65  PI const unsigne
33470 64 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  d char *SQLITE_S
33480 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
33490 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
334a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
334b0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
334c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
334d0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
334e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
334f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33500 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
33510 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
33520 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
33530 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c  _column_type(sql
33540 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33550 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
33560 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  I sqlite3_value 
33570 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
33580 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
33590 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
335a0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
335b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
335c0 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
335d0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
335e0 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54 4f  ect.** DESTRUCTO
335f0 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  R: sqlite3_stmt.
33600 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33610 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75  e3_finalize() fu
33620 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
33630 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72   to delete a [pr
33640 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33650 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  ]..** ^If the mo
33660 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
33670 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74  tion of the stat
33680 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65  ement encountere
33690 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
336a0 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
336b0 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
336c0 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
336d0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
336e0 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
336f0 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
33700 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
33710 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
33720 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
33730 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
33740 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
33750 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
33760 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
33770 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
33780 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
33790 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
337a0 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
337b0 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
337c0 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
337d0 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
337e0 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
337f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33800 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
33810 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
33820 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
33830 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
33840 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
33850 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
33860 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
33870 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
33880 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
33890 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
338a0 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
338b0 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
338c0 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
338d0 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
338e0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
338f0 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
33900 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
33910 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
33920 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
33930 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
33940 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
33950 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
33960 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
33970 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
33980 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
33990 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
339a0 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
339b0 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
339c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
339d0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
339e0 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
339f0 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
33a00 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
33a10 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
33a20 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
33a30 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
33a40 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
33a50 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
33a60 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
33a70 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
33a80 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ption..*/.SQLITE
33a90 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
33aa0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
33ab0 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
33ac0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
33ad0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
33ae0 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
33af0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
33b00 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
33b10 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
33b20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
33b30 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
33b40 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
33b50 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
33b60 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
33b70 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
33b80 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
33b90 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
33ba0 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
33bb0 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
33bc0 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
33bd0 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
33be0 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
33bf0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
33c00 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
33c10 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
33c20 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
33c30 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
33c40 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
33c50 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
33c60 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
33c70 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
33c80 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
33c90 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
33ca0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33cb0 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
33cc0 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
33cd0 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
33ce0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
33cf0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
33d00 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
33d10 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
33d20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
33d30 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
33d40 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
33d50 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
33d60 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
33d70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
33d80 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
33d90 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
33da0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
33db0 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
33dc0 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
33dd0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
33de0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
33df0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
33e00 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
33e10 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
33e20 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
33e30 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
33e40 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
33e50 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
33e60 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
33e70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
33e80 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
33e90 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
33ea0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
33eb0 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
33ec0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
33ed0 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
33ee0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
33ef0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51  tement] S..*/.SQ
33f00 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
33f10 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
33f20 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65  te3_reset(sqlite
33f30 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
33f40 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33f50 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66   Create Or Redef
33f60 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e  ine SQL Function
33f70 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
33f80 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
33f90 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b  n routines}.** K
33fa0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
33fb0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
33fc0 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b  L function}.** K
33fd0 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63  EYWORDS: {applic
33fe0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
33ff0 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20  L functions}.** 
34000 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
34010 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
34020 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
34030 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
34040 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
34050 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
34060 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
34070 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
34080 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
34090 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
340a0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
340b0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
340c0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
340d0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
340e0 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
340f0 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
34100 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
34110 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
34120 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
34130 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
34140 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
34150 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
34160 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
34170 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
34180 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
34190 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
341a0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
341b0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
341c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
341d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
341e0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
341f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
34200 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
34210 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
34220 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
34230 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
34240 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
34250 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
34260 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
34270 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34280 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
34290 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
342a0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
342b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
342c0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
342d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
342e0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
342f0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
34300 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
34310 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
34320 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
34330 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
34340 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
34350 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
34360 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
34370 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
34380 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
34390 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
343a0 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
343b0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
343c0 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
343d0 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
343e0 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
343f0 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
34400 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
34410 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
34420 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
34430 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
34440 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
34450 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
34460 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
34470 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
34480 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
34490 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
344a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
344b0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
344c0 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
344d0 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
344e0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
344f0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
34500 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
34510 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
34520 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
34530 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
34540 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
34550 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
34560 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
34570 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
34580 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
34590 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
345a0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
345b0 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
345c0 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
345d0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
345e0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
345f0 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
34600 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
34610 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
34620 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
34630 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
34640 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
34650 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
34660 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
34670 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69 73   should set this
34680 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
34690 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
346a0 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69 6f  ] if the functio
346b0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
346c0 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71   invokes .** [sq
346d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
346e0 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e  16le()] on an in
346f0 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  put, or [SQLITE_
34700 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65 0a  UTF16BE] if the.
34710 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
34720 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69 74  n invokes [sqlit
34730 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
34740 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74  e()] on an input
34750 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  , or.** [SQLITE_
34760 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69 74  UTF16] if [sqlit
34770 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
34780 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20 5b  )] is used, or [
34790 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a 20  SQLITE_UTF8].** 
347a0 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68 65  otherwise.  ^The
347b0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
347c0 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74  on may be regist
347d0 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74 69  ered multiple ti
347e0 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69 66  mes using.** dif
347f0 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65 64  ferent preferred
34800 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2c   text encodings,
34810 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
34820 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
34830 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63 6f  for.** each enco
34840 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d  ding..** ^When m
34850 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
34860 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
34870 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  ame function are
34880 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69   available, SQLi
34890 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20  te.** will pick 
348a0 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76  the one that inv
348b0 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74 20  olves the least 
348c0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63  amount of data c
348d0 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
348e0 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72   ^The fourth par
348f0 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69 6f  ameter may optio
34900 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77 69  nally be ORed wi
34910 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52  th [SQLITE_DETER
34920 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f 20  MINISTIC].** to 
34930 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65 20  signal that the 
34940 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61 6c  function will al
34950 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20  ways return the 
34960 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76 65  same result give
34970 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69 6e  n.** the same in
34980 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73 69  puts within a si
34990 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
349a0 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66 75  nt.  Most SQL fu
349b0 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20 64  nctions are.** d
349c0 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
349d0 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61 6e  he built-in [ran
349e0 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63 74  dom()] SQL funct
349f0 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70 6c  ion is an exampl
34a00 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74 69  e of a.** functi
34a10 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20 64  on that is not d
34a20 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20 54  eterministic.  T
34a30 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79 20  he SQLite query 
34a40 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65 20  planner is able 
34a50 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61 64  to.** perform ad
34a60 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a  ditional optimiz
34a70 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72 6d  ations on determ
34a80 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  inistic function
34a90 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66 20  s, so use.** of 
34aa0 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  the [SQLITE_DETE
34ab0 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67 20  RMINISTIC] flag 
34ac0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 77  is recommended w
34ad0 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  here possible..*
34ae0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
34af0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
34b00 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
34b10 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
34b20 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
34b30 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
34b40 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
34b50 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
34b60 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
34b70 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
34b80 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
34b90 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
34ba0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
34bb0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
34bc0 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
34bd0 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
34be0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
34bf0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
34c00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
34c10 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
34c20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
34c30 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
34c40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
34c50 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
34c60 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
34c70 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
34c80 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
34c90 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
34ca0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
34cb0 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
34cc0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
34cd0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
34ce0 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
34cf0 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
34d00 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
34d10 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
34d20 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
34d30 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
34d40 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
34d50 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
34d60 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
34d70 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
34d80 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
34d90 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
34da0 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
34db0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
34dc0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
34dd0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
34de0 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
34df0 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
34e00 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
34e10 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
34e20 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
34e30 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
34e40 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
34e50 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
34e60 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
34e70 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
34e80 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
34e90 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
34ea0 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
34eb0 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
34ec0 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
34ed0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
34ee0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
34ef0 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
34f00 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
34f10 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
34f20 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
34f30 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
34f40 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
34f50 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
34f60 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
34f70 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
34f80 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
34f90 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
34fa0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
34fb0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
34fc0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
34fd0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
34fe0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
34ff0 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
35000 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
35010 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
35020 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
35030 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
35040 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
35050 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
35060 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
35070 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
35080 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
35090 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
350a0 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
350b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
350c0 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
350d0 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
350e0 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
350f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
35100 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
35110 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
35120 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
35130 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
35140 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
35150 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
35160 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
35170 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
35180 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
35190 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
351a0 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
351b0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
351c0 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
351d0 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
351e0 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
351f0 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
35200 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
35210 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
35220 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
35230 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
35240 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
35250 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
35260 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
35270 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
35280 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
35290 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
352a0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
352b0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
352c0 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
352d0 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
352e0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
352f0 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
35300 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
35310 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
35320 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
35330 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
35340 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
35350 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
35360 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
35370 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
35380 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
35390 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
353a0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
353b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
353c0 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
353d0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
353e0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
353f0 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
35400 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
35410 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
35420 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
35430 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  L sqlite3_create
35440 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
35450 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
35460 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
35470 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
35480 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
35490 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
354a0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
354b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
354c0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
354d0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
354e0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
354f0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
35500 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
35510 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
35520 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35530 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
35540 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
35550 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  LL sqlite3_creat
35560 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20  e_function16(.  
35570 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
35580 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63  onst void *zFunc
35590 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
355a0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
355b0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
355c0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
355d0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
355e0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
355f0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
35600 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
35610 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
35620 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
35630 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
35640 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
35650 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  xt*).);.SQLITE_A
35660 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
35670 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72  DCALL sqlite3_cr
35680 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
35690 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
356a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
356b0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
356c0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
356d0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
356e0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
356f0 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
35700 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
35710 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
35720 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
35730 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35740 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
35750 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
35760 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
35770 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
35780 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
35790 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
357a0 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
357b0 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
357c0 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
357d0 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
357e0 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
357f0 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
35800 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
35810 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
35820 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
35830 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
35840 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a 20     1    /* IMP: 
35850 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a 2f  R-37514-35566 */
35860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
35870 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
35880 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30 33      /* IMP: R-03
35890 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64 65  371-37637 */.#de
358a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
358b0 36 42 45 20 20 20 20 20 20 20 20 33 20 20 20 20  6BE        3    
358c0 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31 2d  /* IMP: R-51971-
358d0 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e 65  34154 */.#define
358e0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
358f0 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
35900 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
35910 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
35920 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
35930 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44 65        5    /* De
35940 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65 66  precated */.#def
35950 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
35960 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
35970 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
35980 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
35990 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
359a0 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c 61  EF: Function Fla
359b0 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
359c0 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65 20  onstants may be 
359d0 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77 69  ORed together wi
359e0 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
359f0 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65 72  TE_UTF8 | prefer
35a00 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
35a10 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  g] as the fourth
35a20 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
35a30 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35a40 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  function()], [sq
35a50 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35a60 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  ction16()], or.*
35a70 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
35a80 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 5d  e_function_v2()]
35a90 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
35aa0 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
35ab0 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a 2a  C    0x800../*.*
35ac0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
35ad0 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
35ae0 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
35af0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
35b00 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
35b10 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
35b20 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
35b30 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
35b40 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
35b50 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
35b60 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
35b70 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
35b80 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
35b90 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
35ba0 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
35bb0 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
35bc0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
35bd0 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f 67  o encourage prog
35be0 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69 64  rammers to avoid
35bf0 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74 69  .** these functi
35c00 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f 74  ons, we will not
35c10 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74 68   explain what th
35c20 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ey do..*/.#ifnde
35c30 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45  f SQLITE_OMIT_DE
35c40 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f  PRECATED.SQLITE_
35c50 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
35c60 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54 45  CATED int SQLITE
35c70 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
35c80 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
35c90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35ca0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
35cb0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
35cc0 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
35cd0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 70 69  ALL sqlite3_expi
35ce0 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
35cf0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
35d00 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
35d10 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
35d20 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  ALL sqlite3_tran
35d30 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
35d40 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
35d50 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
35d60 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
35d70 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53 51  EPRECATED int SQ
35d80 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
35d90 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
35da0 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
35db0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
35dc0 52 45 43 41 54 45 44 20 76 6f 69 64 20 53 51 4c  RECATED void SQL
35dd0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
35de0 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e  te3_thread_clean
35df0 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  up(void);.SQLITE
35e00 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
35e10 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54  ECATED int SQLIT
35e20 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
35e30 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76  3_memory_alarm(v
35e40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c  oid(*)(void*,sql
35e50 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c  ite3_int64,int),
35e60 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
35e70 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c         void*,sql
35e80 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
35e90 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
35ea0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
35eb0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
35ec0 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 20  meter Values.** 
35ed0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
35ee0 76 61 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20  value.**.** The 
35ef0 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65  C-language imple
35f00 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c  mentation of SQL
35f10 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
35f20 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a  ggregates uses.*
35f30 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e  * this set of in
35f40 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73  terface routines
35f50 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70   to access the p
35f60 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20  arameter values 
35f70 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69  on.** the functi
35f80 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e  on or aggregate.
35f90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
35fa0 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
35fb0 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
35fc0 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
35fd0 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
35fe0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
35ff0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
36000 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
36010 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
36020 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
36030 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
36040 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
36050 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
36060 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
36070 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
36080 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
36090 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
360a0 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
360b0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
360c0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
360d0 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
360e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
360f0 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
36100 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
36110 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
36120 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
36130 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
36140 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
36150 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
36160 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
36170 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
36180 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
36190 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
361a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
361b0 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
361c0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
361d0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
361e0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
361f0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
36200 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
36210 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
36220 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
36230 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
36240 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
36250 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
36260 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
36270 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
36280 20 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74   that these rout
36290 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
362a0 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
362b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
362c0 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
362d0 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
362e0 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
362f0 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
36300 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
36310 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36320 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
36330 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
36340 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
36350 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
36360 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
36370 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
36380 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
36390 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
363a0 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
363b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
363c0 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
363d0 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
363e0 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
363f0 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
36400 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
36410 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
36420 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
36430 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
36440 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
36450 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
36460 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
36470 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
36480 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
36490 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
364a0 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
364b0 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
364c0 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
364d0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
364e0 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
364f0 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
36500 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
36510 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
36520 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
36530 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
36540 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
36550 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
36560 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
36570 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
36580 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
36590 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
365a0 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
365b0 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
365c0 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
365d0 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
365e0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
365f0 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
36600 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
36610 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
36620 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
36630 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
36640 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
36650 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
36660 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
36670 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
36680 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
36690 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
366a0 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
366b0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
366c0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
366d0 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
366e0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
366f0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
36700 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
36710 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
36720 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
36730 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
36740 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
36750 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
36760 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
36770 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
36780 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
36790 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
367a0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51  arameters..*/.SQ
367b0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
367c0 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
367d0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
367e0 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
367f0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
36800 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
36810 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
36820 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
36830 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
36840 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
36850 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
36860 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
36870 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36880 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c  SQLITE_API doubl
36890 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  e SQLITE_STDCALL
368a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
368b0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
368c0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
368d0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
368e0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
368f0 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
36900 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
36910 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
36920 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
36930 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
36940 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
36950 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
36960 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
36970 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
36980 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
36990 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
369a0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
369b0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
369c0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
369d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
369e0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
369f0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
36a00 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
36a10 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
36a20 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
36a30 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36a40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
36a50 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
36a60 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
36a70 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
36a80 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36a90 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
36aa0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
36ab0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
36ac0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36ad0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
36ae0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
36af0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
36b00 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
36b10 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
36b20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
36b30 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
36b40 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
36b50 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
36b60 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
36b70 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  Implementations 
36b80 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  of aggregate SQL
36b90 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74   functions use t
36ba0 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74  his.** routine t
36bb0 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72  o allocate memor
36bc0 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68  y for storing th
36bd0 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  eir state..**.**
36be0 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
36bf0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67   the sqlite3_agg
36c00 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
36c10 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63  ,N) routine is c
36c20 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20  alled .** for a 
36c30 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65  particular aggre
36c40 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53  gate function, S
36c50 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74  QLite.** allocat
36c60 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  es N of memory, 
36c70 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20  zeroes out that 
36c80 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75  memory, and retu
36c90 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  rns a pointer.**
36ca0 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f   to the new memo
36cb0 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61  ry. ^On second a
36cc0 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  nd subsequent ca
36cd0 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  lls to.** sqlite
36ce0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
36cf0 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61  ext() for the sa
36d00 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
36d10 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a  ction instance,.
36d20 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66  ** the same buff
36d30 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  er is returned. 
36d40 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   Sqlite3_aggrega
36d50 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20  te_context() is 
36d60 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  normally.** call
36d70 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68  ed once for each
36d80 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74   invocation of t
36d90 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63  he xStep callbac
36da0 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a  k and then one.*
36db0 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e  * last time when
36dc0 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c   the xFinal call
36dd0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e  back is invoked.
36de0 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73    ^(When no rows
36df0 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67   match.** an agg
36e00 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68  regate query, th
36e10 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61  e xStep() callba
36e20 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67  ck of the aggreg
36e30 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ate function.** 
36e40 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
36e50 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61  s never called a
36e60 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63  nd xFinal() is c
36e70 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e  alled exactly on
36e80 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20  ce..** In those 
36e90 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61  cases, sqlite3_a
36ea0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
36eb0 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c  () might be call
36ec0 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69  ed for the.** fi
36ed0 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69  rst time from wi
36ee0 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e  thin xFinal().)^
36ef0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36f00 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
36f10 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
36f20 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  ne returns a NUL
36f30 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68  L pointer .** wh
36f40 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20  en first called 
36f50 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  if N is less tha
36f60 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
36f70 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72  ro or if a memor
36f80 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72  y.** allocate er
36f90 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a  ror occurs..**.*
36fa0 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f  * ^(The amount o
36fb0 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65  f space allocate
36fc0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67  d by sqlite3_agg
36fd0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
36fe0 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d  ,N) is.** determ
36ff0 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61  ined by the N pa
37000 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74  rameter on first
37010 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
37020 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a  .  Changing the.
37030 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e  ** value of N in
37040 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
37050 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
37060 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
37070 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61  within.** the sa
37080 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  me aggregate fun
37090 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77  ction instance w
370a0 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74  ill not resize t
370b0 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  he memory.** all
370c0 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68  ocation.)^  With
370d0 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  in the xFinal ca
370e0 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75  llback, it is cu
370f0 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a  stomary to set.*
37100 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74  * N=0 in calls t
37110 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
37120 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
37130 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20   so that no .** 
37140 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79  pointless memory
37150 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63   allocations occ
37160 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ur..**.** ^SQLit
37170 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
37180 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
37190 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
371a0 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
371b0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
371c0 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
371d0 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
371e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
371f0 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
37200 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
37210 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
37220 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
37230 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
37240 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
37250 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
37260 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
37270 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
37280 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
37290 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
372a0 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
372b0 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
372c0 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
372d0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
372e0 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
372f0 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
37300 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
37310 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
37320 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51  ITE_API void *SQ
37330 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
37340 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
37350 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
37360 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
37370 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
37380 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
37390 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
373a0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
373b0 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20  3_context.**.** 
373c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
373d0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
373e0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
373f0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
37400 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
37410 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
37420 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
37430 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
37440 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
37450 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
37460 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
37470 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
37480 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
37490 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
374a0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
374b0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
374c0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
374d0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
374e0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
374f0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
37500 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
37510 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
37520 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
37530 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
37540 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37550 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
37560 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
37570 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
37580 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
37590 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
375a0 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
375b0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54 48 4f  nctions.** METHO
375c0 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
375d0 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  xt.**.** ^The sq
375e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
375f0 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
37600 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
37610 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
37620 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
37630 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37640 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
37650 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
37660 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37670 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
37680 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
37690 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
376a0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
376b0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
376c0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
376d0 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
376e0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  function..*/.SQL
376f0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20  ITE_API sqlite3 
37700 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20  *SQLITE_STDCALL 
37710 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
37720 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65  db_handle(sqlite
37730 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a  3_context*);../*
37740 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
37750 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79  nction Auxiliary
37760 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f 44 3a   Data.** METHOD:
37770 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
37780 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
37790 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
377a0 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65  ed by (non-aggre
377b0 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69  gate) SQL functi
377c0 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
377d0 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
377e0 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
377f0 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
37800 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
37810 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
37820 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
37830 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
37840 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
37850 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
37860 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
37870 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
37880 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
37890 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
378a0 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20    An example.** 
378b0 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69  of where this mi
378c0 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73  ght be useful is
378d0 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78   in a regular-ex
378e0 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
378f0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  g.** function. T
37900 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
37910 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
37920 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
37930 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a  n be stored as.*
37940 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
37950 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
37960 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20  attern string.  
37970 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67  .** Then as long
37980 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20   as the pattern 
37990 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74  string remains t
379a0 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20  he same,.** the 
379b0 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
379c0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
379d0 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
379e0 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
379f0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
37a00 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
37a10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
37a20 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
37a30 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
37a40 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
37a50 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
37a60 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
37a70 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
37a80 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
37a90 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
37aa0 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
37ab0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
37ac0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
37ad0 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
37ae0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
37af0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
37b00 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
37b10 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  t, this sqlite3_
37b20 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
37b30 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
37b40 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
37b50 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
37b60 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
37b70 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72  a(C,N,P,X) inter
37b80 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20  face saves P as 
37b90 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
37ba0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
37bb0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
37bc0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37bd0 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75  ction.  ^Subsequ
37be0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
37bf0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
37c00 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20  ata(C,N) return 
37c10 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20  P from the most 
37c20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65  recent.** sqlite
37c30 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
37c40 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74  N,P,X) call if t
37c50 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73  he metadata is s
37c60 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a  till valid or.**
37c70 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74   NULL if the met
37c80 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64  adata has been d
37c90 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66  iscarded..** ^Af
37ca0 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  ter each call to
37cb0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
37cc0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68  data(C,N,P,X) wh
37cd0 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c  ere X is not NUL
37ce0 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  L,.** SQLite wil
37cf0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
37d00 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
37d10 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65   X with paramete
37d20 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f  r P exactly.** o
37d30 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65  nce, when the me
37d40 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72  tadata is discar
37d50 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ded..** SQLite i
37d60 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72  s free to discar
37d70 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61  d the metadata a
37d80 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c  t any time, incl
37d90 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c  uding: <ul>.** <
37da0 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72  li> when the cor
37db0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
37dc0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
37dd0 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  anges, or.** <li
37de0 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  > when [sqlite3_
37df0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
37e00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
37e10 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   is called for t
37e20 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73  he.**      SQL s
37e30 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20  tatement, or.** 
37e40 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65  <li> when sqlite
37e50 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
37e60 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e  is invoked again
37e70 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72   on the same par
37e80 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c  ameter, or.** <l
37e90 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72  i> during the or
37ea0 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73  iginal sqlite3_s
37eb0 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c  et_auxdata() cal
37ec0 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20  l when a memory 
37ed0 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74  .**      allocat
37ee0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
37ef0 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  . </ul>)^.**.** 
37f00 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75  Note the last bu
37f10 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c  llet in particul
37f20 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  ar.  The destruc
37f30 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c  tor X in .** sql
37f40 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
37f50 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20  (C,N,P,X) might 
37f60 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69  be called immedi
37f70 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68  ately, before th
37f80 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  e.** sqlite3_set
37f90 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
37fa0 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e  face even return
37fb0 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65  s.  Hence sqlite
37fc0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a  3_set_auxdata().
37fd0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  ** should be cal
37fe0 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64  led near the end
37ff0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
38000 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
38010 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  and the.** funct
38020 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
38030 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61  on should not ma
38040 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20  ke any use of P 
38050 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33  after.** sqlite3
38060 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68  _set_auxdata() h
38070 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  as been called..
38080 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
38090 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
380a0 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
380b0 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
380c0 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  s for.** functio
380d0 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
380e0 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69  t are compile-ti
380f0 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e  me constants, in
38100 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a  cluding literal.
38110 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
38120 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65  arameters] and e
38130 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f  xpressions compo
38140 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  sed from the sam
38150 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  e.)^.**.** These
38160 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
38170 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
38180 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
38190 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
381a0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
381b0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
381c0 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54  _API void *SQLIT
381d0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
381e0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_get_auxdata(sq
381f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
38200 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41  int N);.SQLITE_A
38210 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f 53  PI void SQLITE_S
38220 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73  TDCALL sqlite3_s
38230 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
38240 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
38250 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
38260 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
38270 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
38280 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
38290 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
382a0 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a  ctor Behavior.**
382b0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
382c0 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
382d0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
382e0 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
382f0 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
38300 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
38310 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
38320 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
38330 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65  ()].  ^If the de
38340 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
38350 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
38360 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
38370 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
38380 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
38390 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
383a0 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
383b0 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
383c0 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
383d0 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54  .  ^The.** SQLIT
383e0 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
383f0 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
38400 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
38410 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
38420 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
38430 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
38440 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
38450 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
38460 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
38470 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
38480 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
38490 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
384a0 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
384b0 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
384c0 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
384d0 63 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79  compilers..*/.ty
384e0 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
384f0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
38500 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
38510 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
38520 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
38530 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
38540 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
38550 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
38560 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
38570 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
38580 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38590 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
385a0 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
385b0 63 74 69 6f 6e 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ction.** METHOD:
385c0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
385d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
385e0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
385f0 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
38600 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
38610 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
38620 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
38630 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
38640 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
38650 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
38660 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
38670 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
38680 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
38690 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
386a0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
386b0 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
386c0 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
386d0 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69  he [parameter bi
386e0 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66  nding] family of
386f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  .** functions us
38700 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ed to bind value
38710 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
38720 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
38730 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
38740 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51  Refer to the [SQ
38750 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63  L parameter] doc
38760 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
38770 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
38780 61 74 69 6f 6