System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 3be71d99121fe5b17f057011025bcf84e7cc6c84:


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 31 2e 31 2e  ersion 3.8.11.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: 57 68 61 74 20 76 65 72 73 69 6f 6e 20 6f 66 20  What version of 
1840: 47 43 43 20 69 73 20 62 65 69 6e 67 20 75 73 65  GCC is being use
1850: 64 2e 20 20 30 20 6d 65 61 6e 73 20 47 43 43 20  d.  0 means GCC 
1860: 69 73 20 6e 6f 74 20 62 65 69 6e 67 20 75 73 65  is not being use
1870: 64 20 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 47 4e  d */.#ifdef __GN
1880: 55 43 5f 5f 0a 23 20 64 65 66 69 6e 65 20 47 43  UC__.# define GC
1890: 43 5f 56 45 52 53 49 4f 4e 20 28 5f 5f 47 4e 55  C_VERSION (__GNU
18a0: 43 5f 5f 2a 31 30 30 30 30 30 30 2b 5f 5f 47 4e  C__*1000000+__GN
18b0: 55 43 5f 4d 49 4e 4f 52 5f 5f 2a 31 30 30 30 2b  UC_MINOR__*1000+
18c0: 5f 5f 47 4e 55 43 5f 50 41 54 43 48 4c 45 56 45  __GNUC_PATCHLEVE
18d0: 4c 5f 5f 29 0a 23 65 6c 73 65 0a 23 20 64 65 66  L__).#else.# def
18e0: 69 6e 65 20 47 43 43 5f 56 45 52 53 49 4f 4e 20  ine GCC_VERSION 
18f0: 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20 4e 65 65  0.#endif../* Nee
1900: 64 65 64 20 66 6f 72 20 76 61 72 69 6f 75 73 20  ded for various 
1910: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e 2e 20 2a  definitions... *
1920: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f 5f  /.#if defined(__
1930: 47 4e 55 43 5f 5f 29 20 26 26 20 21 64 65 66 69  GNUC__) && !defi
1940: 6e 65 64 28 5f 47 4e 55 5f 53 4f 55 52 43 45 29  ned(_GNU_SOURCE)
1950: 0a 23 20 64 65 66 69 6e 65 20 5f 47 4e 55 5f 53  .# define _GNU_S
1960: 4f 55 52 43 45 0a 23 65 6e 64 69 66 0a 0a 23 69  OURCE.#endif..#i
1970: 66 20 64 65 66 69 6e 65 64 28 5f 5f 4f 70 65 6e  f defined(__Open
1980: 42 53 44 5f 5f 29 20 26 26 20 21 64 65 66 69 6e  BSD__) && !defin
1990: 65 64 28 5f 42 53 44 5f 53 4f 55 52 43 45 29 0a  ed(_BSD_SOURCE).
19a0: 23 20 64 65 66 69 6e 65 20 5f 42 53 44 5f 53 4f  # define _BSD_SO
19b0: 55 52 43 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  URCE.#endif../*.
19c0: 2a 2a 20 46 6f 72 20 4d 69 6e 47 57 2c 20 63 68  ** For MinGW, ch
19d0: 65 63 6b 20 74 6f 20 73 65 65 20 69 66 20 77 65  eck to see if we
19e0: 20 63 61 6e 20 69 6e 63 6c 75 64 65 20 74 68 65   can include the
19f0: 20 68 65 61 64 65 72 20 66 69 6c 65 20 63 6f 6e   header file con
1a00: 74 61 69 6e 69 6e 67 20 69 74 73 0a 2a 2a 20 76  taining its.** v
1a10: 65 72 73 69 6f 6e 20 69 6e 66 6f 72 6d 61 74 69  ersion informati
1a20: 6f 6e 2c 20 61 6d 6f 6e 67 20 6f 74 68 65 72 20  on, among other 
1a30: 74 68 69 6e 67 73 2e 20 20 4e 6f 72 6d 61 6c 6c  things.  Normall
1a40: 79 2c 20 74 68 69 73 20 69 6e 74 65 72 6e 61 6c  y, this internal
1a50: 20 4d 69 6e 47 57 0a 2a 2a 20 68 65 61 64 65 72   MinGW.** header
1a60: 20 66 69 6c 65 20 77 6f 75 6c 64 20 5b 6f 6e 6c   file would [onl
1a70: 79 5d 20 62 65 20 69 6e 63 6c 75 64 65 64 20 61  y] be included a
1a80: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
1a90: 6f 74 68 65 72 20 4d 69 6e 47 57 20 68 65 61 64  other MinGW head
1aa0: 65 72 0a 2a 2a 20 66 69 6c 65 73 3b 20 68 6f 77  er.** files; how
1ab0: 65 76 65 72 2c 20 74 68 65 20 63 6f 6e 74 61 69  ever, the contai
1ac0: 6e 65 64 20 76 65 72 73 69 6f 6e 20 69 6e 66 6f  ned version info
1ad0: 72 6d 61 74 69 6f 6e 20 69 73 20 6e 6f 77 20 72  rmation is now r
1ae0: 65 71 75 69 72 65 64 20 62 79 20 74 68 69 73 0a  equired by this.
1af0: 2a 2a 20 68 65 61 64 65 72 20 66 69 6c 65 20 74  ** header file t
1b00: 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 62 69  o work around bi
1b10: 6e 61 72 79 20 63 6f 6d 70 61 74 69 62 69 6c 69  nary compatibili
1b20: 74 79 20 69 73 73 75 65 73 20 28 73 65 65 20 62  ty issues (see b
1b30: 65 6c 6f 77 29 20 61 6e 64 0a 2a 2a 20 74 68 69  elow) and.** thi
1b40: 73 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 6b 6e  s is the only kn
1b50: 6f 77 6e 20 77 61 79 20 74 6f 20 72 65 6c 69 61  own way to relia
1b60: 62 6c 79 20 6f 62 74 61 69 6e 20 69 74 2e 20 20  bly obtain it.  
1b70: 54 68 69 73 20 65 6e 74 69 72 65 20 23 69 66 20  This entire #if 
1b80: 62 6c 6f 63 6b 0a 2a 2a 20 77 6f 75 6c 64 20 62  block.** would b
1b90: 65 20 63 6f 6d 70 6c 65 74 65 6c 79 20 75 6e 6e  e completely unn
1ba0: 65 63 65 73 73 61 72 79 20 69 66 20 74 68 65 72  ecessary if ther
1bb0: 65 20 77 61 73 20 61 6e 79 20 6f 74 68 65 72 20  e was any other 
1bc0: 77 61 79 20 6f 66 20 64 65 74 65 63 74 69 6e 67  way of detecting
1bd0: 0a 2a 2a 20 4d 69 6e 47 57 20 76 69 61 20 74 68  .** MinGW via th
1be0: 65 69 72 20 70 72 65 70 72 6f 63 65 73 73 6f 72  eir preprocessor
1bf0: 20 28 65 2e 67 2e 20 69 66 20 74 68 65 79 20 63   (e.g. if they c
1c00: 75 73 74 6f 6d 69 7a 65 64 20 74 68 65 69 72 20  ustomized their 
1c10: 47 43 43 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  GCC to define.**
1c20: 20 73 6f 6d 65 20 4d 69 6e 47 57 2d 73 70 65 63   some MinGW-spec
1c30: 69 66 69 63 20 6d 61 63 72 6f 73 29 2e 20 20 57  ific macros).  W
1c40: 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f  hen compiling fo
1c50: 72 20 4d 69 6e 47 57 2c 20 65 69 74 68 65 72 20  r MinGW, either 
1c60: 74 68 65 0a 2a 2a 20 5f 48 41 56 45 5f 4d 49 4e  the.** _HAVE_MIN
1c70: 47 57 5f 48 20 6f 72 20 5f 48 41 56 45 5f 5f 4d  GW_H or _HAVE__M
1c80: 49 4e 47 57 5f 48 20 28 6e 6f 74 65 20 74 68 65  INGW_H (note the
1c90: 20 65 78 74 72 61 20 75 6e 64 65 72 73 63 6f 72   extra underscor
1ca0: 65 29 20 6d 61 63 72 6f 20 6d 75 73 74 20 62 65  e) macro must be
1cb0: 0a 2a 2a 20 64 65 66 69 6e 65 64 3b 20 6f 74 68  .** defined; oth
1cc0: 65 72 77 69 73 65 2c 20 64 65 74 65 63 74 69 6f  erwise, detectio
1cd0: 6e 20 6f 66 20 63 6f 6e 64 69 74 69 6f 6e 73 20  n of conditions 
1ce0: 73 70 65 63 69 66 69 63 20 74 6f 20 4d 69 6e 47  specific to MinG
1cf0: 57 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 69 73  W will be.** dis
1d00: 61 62 6c 65 64 2e 0a 2a 2f 0a 23 69 66 20 64 65  abled..*/.#if de
1d10: 66 69 6e 65 64 28 5f 48 41 56 45 5f 4d 49 4e 47  fined(_HAVE_MING
1d20: 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65 20 22  W_H).# include "
1d30: 6d 69 6e 67 77 2e 68 22 0a 23 65 6c 69 66 20 64  mingw.h".#elif d
1d40: 65 66 69 6e 65 64 28 5f 48 41 56 45 5f 5f 4d 49  efined(_HAVE__MI
1d50: 4e 47 57 5f 48 29 0a 23 20 69 6e 63 6c 75 64 65  NGW_H).# include
1d60: 20 22 5f 6d 69 6e 67 77 2e 68 22 0a 23 65 6e 64   "_mingw.h".#end
1d70: 69 66 0a 0a 2f 2a 0a 2a 2a 20 46 6f 72 20 4d 69  if../*.** For Mi
1d80: 6e 47 57 20 76 65 72 73 69 6f 6e 20 34 2e 78 20  nGW version 4.x 
1d90: 28 61 6e 64 20 68 69 67 68 65 72 29 2c 20 63 68  (and higher), ch
1da0: 65 63 6b 20 74 6f 20 73 65 65 20 69 66 20 74 68  eck to see if th
1db0: 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54 49 4d  e _USE_32BIT_TIM
1dc0: 45 5f 54 0a 2a 2a 20 64 65 66 69 6e 65 20 69 73  E_T.** define is
1dd0: 20 72 65 71 75 69 72 65 64 20 74 6f 20 6d 61 69   required to mai
1de0: 6e 74 61 69 6e 20 62 69 6e 61 72 79 20 63 6f 6d  ntain binary com
1df0: 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
1e00: 74 68 65 20 4d 53 56 43 20 72 75 6e 74 69 6d 65  the MSVC runtime
1e10: 0a 2a 2a 20 6c 69 62 72 61 72 79 20 69 6e 20 75  .** library in u
1e20: 73 65 20 28 65 2e 67 2e 20 66 6f 72 20 57 69 6e  se (e.g. for Win
1e30: 64 6f 77 73 20 58 50 29 2e 0a 2a 2f 0a 23 69 66  dows XP)..*/.#if
1e40: 20 21 64 65 66 69 6e 65 64 28 5f 55 53 45 5f 33   !defined(_USE_3
1e50: 32 42 49 54 5f 54 49 4d 45 5f 54 29 20 26 26 20  2BIT_TIME_T) && 
1e60: 21 64 65 66 69 6e 65 64 28 5f 55 53 45 5f 36 34  !defined(_USE_64
1e70: 42 49 54 5f 54 49 4d 45 5f 54 29 20 26 26 20 5c  BIT_TIME_T) && \
1e80: 0a 20 20 20 20 64 65 66 69 6e 65 64 28 5f 57 49  .    defined(_WI
1e90: 4e 33 32 29 20 26 26 20 21 64 65 66 69 6e 65 64  N32) && !defined
1ea0: 28 5f 57 49 4e 36 34 29 20 26 26 20 5c 0a 20 20  (_WIN64) && \.  
1eb0: 20 20 64 65 66 69 6e 65 64 28 5f 5f 4d 49 4e 47    defined(__MING
1ec0: 57 5f 4d 41 4a 4f 52 5f 56 45 52 53 49 4f 4e 29  W_MAJOR_VERSION)
1ed0: 20 26 26 20 5f 5f 4d 49 4e 47 57 5f 4d 41 4a 4f   && __MINGW_MAJO
1ee0: 52 5f 56 45 52 53 49 4f 4e 20 3e 3d 20 34 20 26  R_VERSION >= 4 &
1ef0: 26 20 5c 0a 20 20 20 20 64 65 66 69 6e 65 64 28  & \.    defined(
1f00: 5f 5f 4d 53 56 43 52 54 5f 5f 29 0a 23 20 64 65  __MSVCRT__).# de
1f10: 66 69 6e 65 20 5f 55 53 45 5f 33 32 42 49 54 5f  fine _USE_32BIT_
1f20: 54 49 4d 45 5f 54 0a 23 65 6e 64 69 66 0a 0a 2f  TIME_T.#endif../
1f30: 2a 20 54 68 65 20 70 75 62 6c 69 63 20 53 51 4c  * The public SQL
1f40: 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ite interface.  
1f50: 54 68 65 20 5f 46 49 4c 45 5f 4f 46 46 53 45 54  The _FILE_OFFSET
1f60: 5f 42 49 54 53 20 6d 61 63 72 6f 20 6d 75 73 74  _BITS macro must
1f70: 20 61 70 70 65 61 72 0a 2a 2a 20 66 69 72 73 74   appear.** first
1f80: 20 69 6e 20 51 4e 58 2e 20 20 41 6c 73 6f 2c 20   in QNX.  Also, 
1f90: 74 68 65 20 5f 55 53 45 5f 33 32 42 49 54 5f 54  the _USE_32BIT_T
1fa0: 49 4d 45 5f 54 20 6d 61 63 72 6f 20 6d 75 73 74  IME_T macro must
1fb0: 20 61 70 70 65 61 72 20 66 69 72 73 74 20 66 6f   appear first fo
1fc0: 72 0a 2a 2a 20 4d 69 6e 47 57 2e 0a 2a 2f 0a 2f  r.** MinGW..*/./
1fd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 49  ************** I
1fe0: 6e 63 6c 75 64 65 20 73 71 6c 69 74 65 33 2e 68  nclude sqlite3.h
1ff0: 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f   in the middle o
2000: 66 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a  f sqliteInt.h **
2010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
2020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42  ************** B
2030: 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74 65  egin file sqlite
2040: 33 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  3.h ************
2050: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2060: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f  *************/./
2070: 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65 6d  *.** 2001 Septem
2080: 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68 65  ber 15.**.** The
2090: 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69 6d   author disclaim
20a0: 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20 74  s copyright to t
20b0: 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e  his source code.
20c0: 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a    In place of.**
20d0: 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c   a legal notice,
20e0: 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73 73   here is a bless
20f0: 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61  ing:.**.**    Ma
2100: 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e  y you do good an
2110: 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20  d not evil..**  
2120: 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20 66    May you find f
2130: 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20 79  orgiveness for y
2140: 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72 67  ourself and forg
2150: 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20  ive others..**  
2160: 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65 20    May you share 
2170: 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74 61  freely, never ta
2180: 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20 79  king more than y
2190: 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a  ou give..**.****
21a0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21c0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21d0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21e0: 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68 65  *****.** This he
21f0: 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e 65  ader file define
2200: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
2210: 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65 20  that the SQLite 
2220: 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73 65  library.** prese
2230: 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70 72  nts to client pr
2240: 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43 2d  ograms.  If a C-
2250: 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63 74  function, struct
2260: 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a 2a  ure, datatype,.*
2270: 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64 65  * or constant de
2280: 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  finition does no
2290: 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69 73  t appear in this
22a0: 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20 69   file, then it i
22b0: 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c 69  s.** not a publi
22c0: 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c 69  shed API of SQLi
22d0: 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20 74  te, is subject t
22e0: 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75 74  o change without
22f0: 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64 20  .** notice, and 
2300: 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72 65  should not be re
2310: 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f 67  ferenced by prog
2320: 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53 51  rams that use SQ
2330: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65  Lite..**.** Some
2340: 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74 69   of the definiti
2350: 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e 20  ons that are in 
2360: 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d 61  this file are ma
2370: 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70 65  rked as.** "expe
2380: 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70 65  rimental".  Expe
2390: 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61  rimental interfa
23a0: 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79  ces are normally
23b0: 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65 73   new.** features
23c0: 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64 20   recently added 
23d0: 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20 64  to SQLite.  We d
23e0: 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74 65  o not anticipate
23f0: 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20 65   changes.** to e
2400: 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65  xperimental inte
2410: 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65 72  rfaces but reser
2420: 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f 20  ve the right to 
2430: 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e 67  make minor chang
2440: 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69 65  es.** if experie
2450: 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69 6e  nce from use "in
2460: 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67 65   the wild" sugge
2470: 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73 20  st such changes 
2480: 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a 0a  are prudent..**.
2490: 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c 20  ** The official 
24a0: 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20 64  C-language API d
24b0: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
24c0: 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69 76   SQLite is deriv
24d0: 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d 65  ed.** from comme
24e0: 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c 65  nts in this file
24f0: 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  .  This file is 
2500: 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69 76  the authoritativ
2510: 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20 68  e source.** on h
2520: 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ow SQLite interf
2530: 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73 65  aces are suppose
2540: 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  d to operate..**
2550: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
2560: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
2570: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
2580: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
2590: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
25a0: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
25b0: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
25c0: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
25d0: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
25e0: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
25f0: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
2600: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
2610: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
2620: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
2630: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
2640: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
2650: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
2660: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
2670: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
2680: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
2690: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
26a0: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
26b0: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
26c0: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
26d0: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
26e0: 2a 2f 0a 23 69 66 20 30 0a 65 78 74 65 72 6e 20  */.#if 0.extern 
26f0: 22 43 22 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f  "C" {.#endif.../
2700: 2a 0a 2a 2a 20 50 72 6f 76 69 64 65 20 74 68 65  *.** Provide the
2710: 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76 65 72   ability to over
2720: 72 69 64 65 20 6c 69 6e 6b 61 67 65 20 66 65 61  ride linkage fea
2730: 74 75 72 65 73 20 6f 66 20 74 68 65 20 69 6e 74  tures of the int
2740: 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 69 66 6e 64  erface..*/.#ifnd
2750: 65 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  ef SQLITE_EXTERN
2760: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2770: 5f 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23  _EXTERN extern.#
2780: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
2790: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e  LITE_API.# defin
27a0: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e  e SQLITE_API.#en
27b0: 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  dif.#ifndef SQLI
27c0: 54 45 5f 43 44 45 43 4c 0a 23 20 64 65 66 69 6e  TE_CDECL.# defin
27d0: 65 20 53 51 4c 49 54 45 5f 43 44 45 43 4c 0a 23  e SQLITE_CDECL.#
27e0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
27f0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
2800: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
2810: 43 41 4c 4c 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  CALL.#endif../*.
2820: 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70 20 6d  ** These no-op m
2830: 61 63 72 6f 73 20 61 72 65 20 75 73 65 64 20 69  acros are used i
2840: 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74 65 72  n front of inter
2850: 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20 74 68  faces to mark th
2860: 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ose.** interface
2870: 73 20 61 73 20 65 69 74 68 65 72 20 64 65 70 72  s as either depr
2880: 65 63 61 74 65 64 20 6f 72 20 65 78 70 65 72 69  ecated or experi
2890: 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61 70 70  mental.  New app
28a0: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
28b0: 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65 70 72  uld not use depr
28c0: 65 63 61 74 65 64 20 69 6e 74 65 72 66 61 63 65  ecated interface
28d0: 73 20 2d 20 74 68 65 79 20 61 72 65 20 73 75 70  s - they are sup
28e0: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
28f0: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2900: 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70  ility only.  App
2910: 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73  lication writers
2920: 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65   should be aware
2930: 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d   that.** experim
2940: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
2950: 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20   are subject to 
2960: 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20  change in point 
2970: 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
2980: 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65  These macros use
2990: 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20  d to resolve to 
29a0: 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66  various kinds of
29b0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
29c0: 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65  that.** would ge
29d0: 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d  nerate warning m
29e0: 65 73 73 61 67 65 73 20 77 68 65 6e 20 74 68 65  essages when the
29f0: 79 20 77 65 72 65 20 75 73 65 64 2e 20 20 42 75  y were used.  Bu
2a00: 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c  t that.** compil
2a10: 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75  er magic ended u
2a20: 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63  p generating suc
2a30: 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75  h a flurry of bu
2a40: 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61  g reports.** tha
2a50: 74 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20  t we have taken 
2a60: 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67  it all out and g
2a70: 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e  one back to usin
2a80: 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70  g simple.** noop
2a90: 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66   macros..*/.#def
2aa0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45  ine SQLITE_DEPRE
2ab0: 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51  CATED.#define SQ
2ac0: 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
2ad0: 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20  L../*.** Ensure 
2ae0: 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65  these symbols we
2af0: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
2b00: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
2b10: 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a  header file..*/.
2b20: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45  #ifdef SQLITE_VE
2b30: 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51  RSION.# undef SQ
2b40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e  LITE_VERSION.#en
2b50: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54  dif.#ifdef SQLIT
2b60: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
2b70: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
2b80: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
2b90: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2ba0: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
2bb0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
2bc0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a  ion Numbers.**.*
2bd0: 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f  * ^(The [SQLITE_
2be0: 56 45 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72  VERSION] C prepr
2bf0: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e  ocessor macro in
2c00: 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68   the sqlite3.h h
2c10: 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74  eader.** evaluat
2c20: 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c  es to a string l
2c30: 69 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74  iteral that is t
2c40: 68 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  he SQLite versio
2c50: 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  n in the.** form
2c60: 61 74 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65  at "X.Y.Z" where
2c70: 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20   X is the major 
2c80: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28  version number (
2c90: 61 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20  always 3 for.** 
2ca0: 53 51 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69  SQLite3) and Y i
2cb0: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73  s the minor vers
2cc0: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a  ion number and Z
2cd0: 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20   is the release 
2ce0: 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54  number.)^.** ^(T
2cf0: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
2d00: 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65  ON_NUMBER] C pre
2d10: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
2d20: 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69  resolves to an i
2d30: 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74  nteger.** with t
2d40: 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30  he value (X*1000
2d50: 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a  000 + Y*1000 + Z
2d60: 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e  ) where X, Y, an
2d70: 64 20 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65  d Z are the same
2d80: 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64  .** numbers used
2d90: 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53   in [SQLITE_VERS
2da0: 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53  ION].)^.** The S
2db0: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
2dc0: 4d 42 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76  MBER for any giv
2dd0: 65 6e 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  en release of SQ
2de0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a  Lite will also.*
2df0: 2a 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  * be larger than
2e00: 20 74 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f   the release fro
2e10: 6d 20 77 68 69 63 68 20 69 74 20 69 73 20 64 65  m which it is de
2e20: 72 69 76 65 64 2e 20 20 45 69 74 68 65 72 20 59  rived.  Either Y
2e30: 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64   will.** be held
2e40: 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20   constant and Z 
2e50: 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e  will be incremen
2e60: 74 65 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69  ted or else Y wi
2e70: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
2e80: 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20  d.** and Z will 
2e90: 62 65 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f  be reset to zero
2ea0: 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65  ..**.** Since ve
2eb0: 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51  rsion 3.6.18, SQ
2ec0: 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65  Lite source code
2ed0: 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64   has been stored
2ee0: 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72   in the.** <a hr
2ef0: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66  ef="http://www.f
2f00: 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e  ossil-scm.org/">
2f10: 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61  Fossil configura
2f20: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a  tion management.
2f30: 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20  ** system</a>.  
2f40: 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  ^The SQLITE_SOUR
2f50: 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c  CE_ID macro eval
2f60: 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74  uates to.** a st
2f70: 72 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74  ring which ident
2f80: 69 66 69 65 73 20 61 20 70 61 72 74 69 63 75 6c  ifies a particul
2f90: 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53  ar check-in of S
2fa0: 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20  QLite.** within 
2fb0: 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  its configuratio
2fc0: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73  n management sys
2fd0: 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  tem.  ^The SQLIT
2fe0: 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73  E_SOURCE_ID.** s
2ff0: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74  tring contains t
3000: 68 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  he date and time
3010: 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e   of the check-in
3020: 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48   (UTC) and an SH
3030: 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68  A1.** hash of th
3040: 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20  e entire source 
3050: 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  tree..**.** See 
3060: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c  also: [sqlite3_l
3070: 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a  ibversion()],.**
3080: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
3090: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20  sion_number()], 
30a0: 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  [sqlite3_sourcei
30b0: 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
30c0: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20  _version()] and 
30d0: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69  [sqlite_source_i
30e0: 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  d()]..*/.#define
30f0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20   SQLITE_VERSION 
3100: 20 20 20 20 20 20 20 22 33 2e 38 2e 31 31 2e 31         "3.8.11.1
3110: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ".#define SQLITE
3120: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
3130: 33 30 30 38 30 31 31 0a 23 64 65 66 69 6e 65 20  3008011.#define 
3140: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
3150: 20 20 20 20 20 20 22 32 30 31 35 2d 30 37 2d 32        "2015-07-2
3160: 39 20 32 30 3a 30 30 3a 35 37 20 63 66 35 33 38  9 20:00:57 cf538
3170: 65 32 37 38 33 65 34 36 38 62 62 63 32 35 65 37  e2783e468bbc25e7
3180: 63 62 32 61 39 65 65 36 34 64 33 65 30 65 38 30  cb2a9ee64d3e0e80
3190: 62 32 66 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  b2f"../*.** CAPI
31a0: 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
31b0: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
31c0: 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52  umbers.** KEYWOR
31d0: 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73  DS: sqlite3_vers
31e0: 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75  ion, sqlite3_sou
31f0: 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  rceid.**.** Thes
3200: 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f  e interfaces pro
3210: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e  vide the same in
3220: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65  formation as the
3230: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
3240: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  ],.** [SQLITE_VE
3250: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61  RSION_NUMBER], a
3260: 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  nd [SQLITE_SOURC
3270: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
3280: 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62  ssor macros.** b
3290: 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65  ut are associate
32a0: 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  d with the libra
32b0: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ry instead of th
32c0: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20  e header file.  
32d0: 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72  ^(Cautious.** pr
32e0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
32f0: 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29  include assert()
3300: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
3310: 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  heir application
3320: 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68   to.** verify th
3330: 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  at values return
3340: 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65  ed by these inte
3350: 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65  rfaces match the
3360: 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68   macros in.** th
3370: 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68  e header, and th
3380: 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 20 74  us insure that t
3390: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
33a0: 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
33b0: 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72  th matching libr
33c0: 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66  ary and header f
33d0: 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  iles..**.** <blo
33e0: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
33f0: 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33   assert( sqlite3
3400: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
3410: 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52  er()==SQLITE_VER
3420: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a  SION_NUMBER );.*
3430: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
3440: 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  (sqlite3_sourcei
3450: 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43  d(),SQLITE_SOURC
3460: 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61  E_ID)==0 );.** a
3470: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71  ssert( strcmp(sq
3480: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
3490: 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  (),SQLITE_VERSIO
34a0: 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72  N)==0 );.** </pr
34b0: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
34c0: 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
34d0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
34e0: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63  tring constant c
34f0: 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74  ontains the text
3500: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53   of [SQLITE_VERS
3510: 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20  ION].** macro.  
3520: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62  ^The sqlite3_lib
3530: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  version() functi
3540: 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  on returns a poi
3550: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74  nter to the.** t
3560: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65  o the sqlite3_ve
3570: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
3580: 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71  onstant.  The sq
3590: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
35a0: 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ().** function i
35b0: 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75  s provided for u
35c0: 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65  se in DLLs since
35d0: 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c   DLL users usual
35e0: 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a  ly do not have.*
35f0: 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20  * direct access 
3600: 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  to string consta
3610: 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44  nts within the D
3620: 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  LL.  ^The.** sql
3630: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
3640: 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f  number() functio
3650: 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  n returns an int
3660: 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a  eger equal to.**
3670: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
3680: 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20  _NUMBER].  ^The 
3690: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
36a0: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
36b0: 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  rns .** a pointe
36c0: 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f  r to a string co
36d0: 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c  nstant whose val
36e0: 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  ue is the same a
36f0: 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  s the .** [SQLIT
3700: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
3710: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
3720: 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  o..**.** See als
3730: 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69  o: [sqlite_versi
3740: 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
3750: 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a  e_source_id()]..
3760: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
3770: 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33  nst char sqlite3
3780: 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c  _version[] = SQL
3790: 49 54 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c  ITE_VERSION;.SQL
37a0: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
37b0: 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
37c0: 4c 4c 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  LL sqlite3_libve
37d0: 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c  rsion(void);.SQL
37e0: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
37f0: 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
3800: 4c 4c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  LL sqlite3_sourc
3810: 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  eid(void);.SQLIT
3820: 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
3830: 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
3840: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
3850: 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a  er(void);../*.**
3860: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
3870: 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d 70  ime Library Comp
3880: 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 20  ilation Options 
3890: 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a 2a  Diagnostics.**.*
38a0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
38b0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
38c0: 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  d() function ret
38d0: 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a 20  urns 0 or 1 .** 
38e0: 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74 68  indicating wheth
38f0: 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65 64  er the specified
3900: 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66 69   option was defi
3910: 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70 69  ned at .** compi
3920: 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 53  le time.  ^The S
3930: 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d 61  QLITE_ prefix ma
3940: 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f  y be omitted fro
3950: 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f 6e  m the .** option
3960: 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f 20   name passed to 
3970: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
3980: 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20 0a  ption_used().  .
3990: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
39a0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
39b0: 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  _get() function 
39c0: 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e 67  allows iterating
39d0: 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69 73  .** over the lis
39e0: 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68 61  t of options tha
39f0: 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20 61  t were defined a
3a00: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20 62  t compile time b
3a10: 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20 74  y.** returning t
3a20: 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65 20  he N-th compile 
3a30: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72 69  time option stri
3a40: 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f 75  ng.  ^If N is ou
3a50: 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20 73  t of range,.** s
3a60: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
3a70: 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75 72  tion_get() retur
3a80: 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
3a90: 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  r.  ^The SQLITE_
3aa0: 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20 6f   .** prefix is o
3ab0: 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79 20  mitted from any 
3ac0: 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
3ad0: 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
3ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
3af0: 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70 70  t()..**.** ^Supp
3b00: 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61 67  ort for the diag
3b10: 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e 73  nostic functions
3b20: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
3b30: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a 2a  option_used().**
3b40: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6d   and sqlite3_com
3b50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
3b60: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20   may be omitted 
3b70: 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74 68  by specifying th
3b80: 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4d  e .** [SQLITE_OM
3b90: 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e  IT_COMPILEOPTION
3ba0: 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20 61  _DIAGS] option a
3bb0: 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 0a  t compile time..
3bc0: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
3bd0: 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b 73  SQL functions [s
3be0: 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70 74  qlite_compileopt
3bf0: 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a  ion_used()] and.
3c00: 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ** [sqlite_compi
3c10: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d 20  leoption_get()] 
3c20: 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c 65  and the [compile
3c30: 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61 5d  _options pragma]
3c40: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
3c50: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
3c60: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51 4c  OPTION_DIAGS.SQL
3c70: 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
3c80: 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
3c90: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
3ca0: 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68 61 72  _used(const char
3cb0: 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53 51 4c   *zOptName);.SQL
3cc0: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
3cd0: 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  ar *SQLITE_STDCA
3ce0: 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  LL sqlite3_compi
3cf0: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74  leoption_get(int
3d00: 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a   N);.#endif../*.
3d10: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73  ** CAPI3REF: Tes
3d20: 74 20 54 6f 20 53 65 65 20 49 66 20 54 68 65 20  t To See If The 
3d30: 4c 69 62 72 61 72 79 20 49 73 20 54 68 72 65 61  Library Is Threa
3d40: 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  dsafe.**.** ^The
3d50: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
3d60: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  afe() function r
3d70: 65 74 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61  eturns zero if a
3d80: 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51  nd only if.** SQ
3d90: 4c 69 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65  Lite was compile
3da0: 64 20 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20  d with mutexing 
3db0: 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65  code omitted due
3dc0: 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   to the.** [SQLI
3dd0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63  TE_THREADSAFE] c
3de0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
3df0: 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20  on being set to 
3e00: 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  0..**.** SQLite 
3e10: 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  can be compiled 
3e20: 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20  with or without 
3e30: 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a  mutexes.  When.*
3e40: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
3e50: 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 65 70  READSAFE] C prep
3e60: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69  rocessor macro i
3e70: 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65  s 1 or 2, mutexe
3e80: 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
3e90: 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74   and SQLite is t
3ea0: 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e  hreadsafe.  When
3eb0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
3ec0: 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72  THREADSAFE] macr
3ed0: 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20  o is 0, .** the 
3ee0: 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74  mutexes are omit
3ef0: 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68  ted.  Without th
3f00: 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73  e mutexes, it is
3f10: 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20   not safe.** to 
3f20: 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75  use SQLite concu
3f30: 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72  rrently from mor
3f40: 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61  e than one threa
3f50: 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e  d..**.** Enablin
3f60: 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73  g mutexes incurs
3f70: 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65   a measurable pe
3f80: 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74  rformance penalt
3f90: 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65  y..** So if spee
3fa0: 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69  d is of utmost i
3fb0: 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61  mportance, it ma
3fc0: 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73  kes sense to dis
3fd0: 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  able.** the mute
3fe0: 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61  xes.  But for ma
3ff0: 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75  ximum safety, mu
4000: 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20  texes should be 
4010: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65  enabled..** ^The
4020: 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
4030: 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73  r is for mutexes
4040: 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a   to be enabled..
4050: 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
4060: 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
4070: 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69   by an applicati
4080: 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  on to make sure 
4090: 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73  that the.** vers
40a0: 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68  ion of SQLite th
40b0: 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67  at it is linking
40c0: 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d   against was com
40d0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
40e0: 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69 6e  e desired settin
40f0: 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  g of the [SQLITE
4100: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
4110: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ro..**.** This i
4120: 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65  nterface only re
4130: 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d  ports on the com
4140: 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20  pile-time mutex 
4150: 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68  setting.** of th
4160: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
4170: 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20  SAFE] flag.  If 
4180: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
4190: 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54  ed with.** SQLIT
41a0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f  E_THREADSAFE=1 o
41b0: 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65  r =2 then mutexe
41c0: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
41d0: 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20   default but.** 
41e0: 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20  can be fully or 
41f0: 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c  partially disabl
4200: 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20  ed using a call 
4210: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  to [sqlite3_conf
4220: 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68  ig()].** with th
4230: 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f  e verbs [SQLITE_
4240: 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
4250: 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EAD], [SQLITE_CO
4260: 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
4270: 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
4280: 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
4290: 45 44 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75  ED].  ^(The retu
42a0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a  rn value of the.
42b0: 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  ** sqlite3_threa
42c0: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
42d0: 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20   shows only the 
42e0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
42f0: 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61  ting of.** threa
4300: 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e  d safety, not an
4310: 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67  y run-time chang
4320: 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74 69  es to that setti
4330: 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71  ng made by.** sq
4340: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20  lite3_config(). 
4350: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
4360: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
4370: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68   from sqlite3_th
4380: 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73  readsafe().** is
4390: 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61   unchanged by ca
43a0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
43b0: 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  onfig().)^.**.**
43c0: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
43d0: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65  ing mode] docume
43e0: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
43f0: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
4400: 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  on..*/.SQLITE_AP
4410: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
4420: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 68 72  CALL sqlite3_thr
4430: 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a  eadsafe(void);..
4440: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
4450: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
4460: 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45  ion Handle.** KE
4470: 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73  YWORDS: {databas
4480: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64  e connection} {d
4490: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
44a0: 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20  ons}.**.** Each 
44b0: 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61  open SQLite data
44c0: 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e  base is represen
44d0: 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72  ted by a pointer
44e0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
44f0: 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65  of.** the opaque
4500: 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64   structure named
4510: 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20   "sqlite3".  It 
4520: 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69  is useful to thi
4530: 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33  nk of an sqlite3
4540: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61  .** pointer as a
4550: 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b  n object.  The [
4560: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
4570: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
4580: 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
4590: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
45a0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69  interfaces are i
45b0: 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c  ts constructors,
45c0: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
45d0: 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ose()].** and [s
45e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
45f0: 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72  )] are its destr
4600: 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61  uctors.  There a
4610: 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  re many other.**
4620: 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63   interfaces (suc
4630: 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  h as.** [sqlite3
4640: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
4650: 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
4660: 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64  function()], and
4670: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
4680: 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20  y_timeout()] to 
4690: 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20  name but three) 
46a0: 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73  that are methods
46b0: 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   on an.** sqlite
46c0: 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70  3 object..*/.typ
46d0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
46e0: 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a  te3 sqlite3;../*
46f0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34  .** CAPI3REF: 64
4700: 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70  -Bit Integer Typ
4710: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
4720: 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c  sqlite_int64 sql
4730: 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a  ite_uint64.**.**
4740: 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69   Because there i
4750: 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66  s no cross-platf
4760: 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69  orm way to speci
4770: 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  fy 64-bit intege
4780: 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74  r types.** SQLit
4790: 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64  e includes typed
47a0: 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73  efs for 64-bit s
47b0: 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e  igned and unsign
47c0: 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a  ed integers..**.
47d0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
47e0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33  nt64 and sqlite3
47f0: 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20  _uint64 are the 
4800: 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64  preferred type d
4810: 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54  efinitions..** T
4820: 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  he sqlite_int64 
4830: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
4840: 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70  4 types are supp
4850: 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61  orted for backwa
4860: 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  rds.** compatibi
4870: 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a  lity only..**.**
4880: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
4890: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69  t64 and sqlite_i
48a0: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
48b0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
48c0: 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d  ues.** between -
48d0: 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35  9223372036854775
48e0: 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32  808 and +9223372
48f0: 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63  036854775807 inc
4900: 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a  lusive.  ^The.**
4910: 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
4920: 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  and sqlite_uint6
4930: 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72  4 types can stor
4940: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
4950: 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61   .** between 0 a
4960: 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37  nd +184467440737
4970: 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69  09551615 inclusi
4980: 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  ve..*/.#ifdef SQ
4990: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a  LITE_INT64_TYPE.
49a0: 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45    typedef SQLITE
49b0: 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69  _INT64_TYPE sqli
49c0: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
49d0: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c  def unsigned SQL
49e0: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
49f0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
4a00: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
4a10: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
4a20: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
4a30: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
4a40: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
4a50: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
4a60: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
4a70: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
4a80: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
4a90: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
4aa0: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
4ab0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
4ac0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
4ad0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
4ae0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
4af0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
4b00: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
4b10: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
4b20: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
4b30: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
4b40: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
4b50: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
4b60: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
4b70: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
4b80: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
4b90: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
4ba0: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
4bb0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
4bc0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
4bd0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
4be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4bf0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
4c00: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
4c10: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
4c20: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
4c30: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
4c40: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
4c50: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
4c60: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
4c70: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
4c80: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
4c90: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
4ca0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
4cb0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
4cc0: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
4cd0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
4ce0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
4cf0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
4d00: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
4d10: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
4d20: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
4d30: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
4d40: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
4d50: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
4d60: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
4d70: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
4d80: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
4d90: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
4da0: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
4db0: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
4dc0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
4dd0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
4de0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4df0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
4e00: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
4e10: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
4e20: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
4e30: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
4e40: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
4e50: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
4e60: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
4e70: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
4e80: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
4e90: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
4ea0: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
4eb0: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
4ec0: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
4ed0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
4ee0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
4ef0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
4f00: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
4f10: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
4f20: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
4f30: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
4f40: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
4f50: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
4f60: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
4f70: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
4f80: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
4f90: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
4fa0: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
4fb0: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
4fc0: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
4fd0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
4fe0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
4ff0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
5000: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
5010: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
5020: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
5030: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
5040: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
5050: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
5060: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
5070: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
5080: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
5090: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
50a0: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
50b0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
50c0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
50d0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
50e0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
50f0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
5100: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
5110: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
5120: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
5130: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
5140: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
5150: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
5160: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
5170: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
5180: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
5190: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
51a0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
51b0: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
51c0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
51d0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
51e0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
51f0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
5200: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
5210: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
5220: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
5230: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
5240: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
5250: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
5260: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
5270: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
5280: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
5290: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
52a0: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
52b0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
52c0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
52d0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
52e0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
52f0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
5300: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
5310: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
5320: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
5330: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
5340: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
5350: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
5360: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
5370: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
5380: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
5390: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
53a0: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
53b0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
53c0: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
53d0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
53e0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
53f0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
5400: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
5410: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
5420: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
5430: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
5440: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
5450: 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
5460: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71  sqlite3_close(sq
5470: 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f  lite3*);.SQLITE_
5480: 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
5490: 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
54a0: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
54b0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
54c0: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
54d0: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
54e0: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
54f0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
5500: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
5510: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
5520: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
5530: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
5540: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
5550: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
5560: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
5570: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
5580: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
5590: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
55a0: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
55b0: 65 72 66 61 63 65 0a 2a 2a 20 4d 45 54 48 4f 44  erface.** METHOD
55c0: 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
55d0: 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  The sqlite3_exec
55e0: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
55f0: 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72  a convenience wr
5600: 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
5610: 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
5620: 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  _v2()], [sqlite3
5630: 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73  _step()], and [s
5640: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
5650: 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f  )],.** that allo
5660: 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ws an applicatio
5670: 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c  n to run multipl
5680: 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20  e statements of 
5690: 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68  SQL.** without h
56a0: 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c  aving to use a l
56b0: 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a  ot of C code. .*
56c0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
56d0: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
56e0: 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20  ce runs zero or 
56f0: 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64  more UTF-8 encod
5700: 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e  ed,.** semicolon
5710: 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74  -separate SQL st
5720: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
5730: 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67  into its 2nd arg
5740: 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65  ument,.** in the
5750: 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20   context of the 
5760: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
5770: 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20  tion] passed in 
5780: 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72  as its 1st.** ar
5790: 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  gument.  ^If the
57a0: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
57b0: 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72  on of the 3rd ar
57c0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c  gument to.** sql
57d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e  ite3_exec() is n
57e0: 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74  ot NULL, then it
57f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20   is invoked for 
5800: 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a  each result row.
5810: 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66  ** coming out of
5820: 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53   the evaluated S
5830: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20  QL statements.  
5840: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
5850: 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  t to.** sqlite3_
5860: 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65  exec() is relaye
5870: 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65  d through to the
5880: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66   1st argument of
5890: 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63   each.** callbac
58a0: 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e  k invocation.  ^
58b0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
58c0: 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
58d0: 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20  e3_exec().** is 
58e0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61  NULL, then no ca
58f0: 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69  llback is ever i
5900: 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c  nvoked and resul
5910: 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67  t rows are.** ig
5920: 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  nored..**.** ^If
5930: 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
5940: 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e   while evaluatin
5950: 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  g the SQL statem
5960: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
5970: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
5980: 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69  (), then executi
5990: 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  on of the curren
59a0: 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70  t statement stop
59b0: 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75  s and.** subsequ
59c0: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61  ent statements a
59d0: 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66  re skipped.  ^If
59e0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
59f0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
5a00: 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  ec().** is not N
5a10: 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72  ULL then any err
5a20: 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72  or message is wr
5a30: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
5a40: 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  y obtained.** fr
5a50: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
5a60: 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64  oc()] and passed
5a70: 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68   back through th
5a80: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e  e 5th parameter.
5a90: 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d  .** To avoid mem
5aa0: 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61  ory leaks, the a
5ab0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
5ac0: 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  d invoke [sqlite
5ad0: 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20  3_free()].** on 
5ae0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
5af0: 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74  rings returned t
5b00: 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70  hrough the 5th p
5b10: 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f  arameter of.** o
5b20: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
5b30: 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72   after the error
5b40: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
5b50: 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65  is no longer nee
5b60: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ded..** ^If the 
5b70: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
5b80: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
5b90: 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20  is not NULL and 
5ba0: 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63  no errors.** occ
5bb0: 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ur, then sqlite3
5bc0: 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65  _exec() sets the
5bd0: 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20   pointer in its 
5be0: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
5bf0: 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20  .** NULL before 
5c00: 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a  returning..**.**
5c10: 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f   ^If an sqlite3_
5c20: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
5c30: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
5c40: 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  , the sqlite3_ex
5c50: 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  ec().** routine 
5c60: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41  returns SQLITE_A
5c70: 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76  BORT without inv
5c80: 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61  oking the callba
5c90: 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20  ck again and.** 
5ca0: 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20  without running 
5cb0: 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53  any subsequent S
5cc0: 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
5cd0: 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72  *.** ^The 2nd ar
5ce0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
5cf0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
5d00: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69  lback function i
5d10: 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
5d20: 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
5d30: 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20  e result.  ^The 
5d40: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  3rd argument to 
5d50: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
5d60: 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ().** callback i
5d70: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
5d80: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
5d90: 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66  s obtained as if
5da0: 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
5db0: 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
5dc0: 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63  , one for each c
5dd0: 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65  olumn.  ^If an e
5de0: 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72  lement of a.** r
5df0: 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c  esult row is NUL
5e00: 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65  L then the corre
5e10: 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20  sponding string 
5e20: 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a  pointer for the.
5e30: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
5e40: 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  ) callback is a 
5e50: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
5e60: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
5e70: 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74   to the.** sqlit
5e80: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
5e90: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
5ea0: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
5eb0: 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68  rings where each
5ec0: 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73  .** entry repres
5ed0: 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ents the name of
5ee0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72   corresponding r
5ef0: 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20  esult column as 
5f00: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
5f10: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
5f20: 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _name()]..**.** 
5f30: 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61  ^If the 2nd para
5f40: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
5f50: 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c  _exec() is a NUL
5f60: 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69  L pointer, a poi
5f70: 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d  nter.** to an em
5f80: 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61  pty string, or a
5f90: 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f   pointer that co
5fa0: 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74  ntains only whit
5fb0: 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a  espace and/or .*
5fc0: 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20  * SQL comments, 
5fd0: 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74  then no SQL stat
5fe0: 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75  ements are evalu
5ff0: 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74  ated and the dat
6000: 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20  abase.** is not 
6010: 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52  changed..**.** R
6020: 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a  estrictions:.**.
6030: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
6040: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
6050: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
6060: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
6070: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
6080: 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20  ec().**      is 
6090: 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e  a valid and open
60a0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
60b0: 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20  ction]..** <li> 
60c0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
60d0: 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
60e0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
60f0: 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
6100: 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68  ed by.**      th
6110: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
6120: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
6130: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
6140: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
6150: 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  g..** <li> The a
6160: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
6170: 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53  not modify the S
6180: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
6190: 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  t passed into.**
61a0: 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61        the 2nd pa
61b0: 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
61c0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
61d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
61e0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f  s running..** </
61f0: 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul>.*/.SQLITE_AP
6200: 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
6210: 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 65  CALL sqlite3_exe
6220: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  c(.  sqlite3*,  
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: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
6260: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
6270: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
6280: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6290: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
62a0: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
62b0: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28  int (*callback)(
62c0: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
62d0: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61  ,char**),  /* Ca
62e0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
62f0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20  */.  void *,    
6300: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6310: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6320: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20  /* 1st argument 
6330: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20  to callback */. 
6340: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **errmsg  
6350: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6360: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
6370: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
6380: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   here */.);../*.
6390: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
63a0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
63b0: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
63c0: 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d  ode definitions}
63d0: 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69  .**.** Many SQLi
63e0: 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  te functions ret
63f0: 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72  urn an integer r
6400: 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20  esult code from 
6410: 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a  the set shown.**
6420: 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74   here in order t
6430: 6f 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65  o indicate succe
6440: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a  ss or failure..*
6450: 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63  *.** New error c
6460: 6f 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65  odes may be adde
6470: 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73  d in future vers
6480: 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
6490: 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
64a0: 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
64b0: 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e   code definition
64c0: 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s].*/.#define SQ
64d0: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
64e0: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
64f0: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
6500: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
6510: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
6520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
6530: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
6540: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
6550: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
6560: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6570: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
6580: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
6590: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
65a0: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
65b0: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
65c0: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
65d0: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
65e0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
65f0: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
6600: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
6610: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
6620: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
6630: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
6640: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
6650: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
6660: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
6670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6680: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
6690: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
66a0: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
66b0: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
66c0: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
66d0: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
66e0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
66f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6700: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
6710: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
6720: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
6730: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
6740: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
6750: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
6760: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
6770: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
6780: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
6790: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
67a0: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
67b0: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
67c0: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
67d0: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
67e0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
67f0: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
6800: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
6810: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
6820: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6830: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
6840: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
6850: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
6860: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
6870: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6880: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
6890: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
68a0: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
68b0: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
68c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
68d0: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
68e0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
68f0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
6900: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
6910: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
6920: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
6930: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
6940: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
6950: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
6960: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
6970: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
6980: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6990: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
69a0: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
69b0: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
69c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
69d0: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
69e0: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
69f0: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
6a00: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
6a10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
6a20: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
6a30: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
6a40: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
6a50: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
6a60: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
6a70: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
6a80: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
6a90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
6aa0: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
6ab0: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
6ac0: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
6ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
6ae0: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
6af0: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
6b00: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
6b10: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
6b20: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
6b30: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
6b40: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
6b50: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
6b60: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
6b70: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
6b80: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
6b90: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
6ba0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
6bb0: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
6bc0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
6bd0: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
6be0: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
6bf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
6c00: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
6c10: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
6c20: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
6c30: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
6c40: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
6c50: 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f        27   /* No
6c60: 74 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d  tifications from
6c70: 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a   sqlite3_log() *
6c80: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6c90: 5f 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20  _WARNING     28 
6ca0: 20 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72    /* Warnings fr
6cb0: 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  om sqlite3_log()
6cc0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
6cd0: 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31  TE_ROW         1
6ce0: 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  00  /* sqlite3_s
6cf0: 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65  tep() has anothe
6d00: 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23  r row ready */.#
6d10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f  define SQLITE_DO
6d20: 4e 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f  NE        101  /
6d30: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
6d40: 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
6d50: 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e  ecuting */./* en
6d60: 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73  d-of-error-codes
6d70: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
6d80: 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65  REF: Extended Re
6d90: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
6da0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
6db0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65  d result code de
6dc0: 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  finitions}.**.**
6dd0: 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20   In its default 
6de0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53  configuration, S
6df0: 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e  QLite API routin
6e00: 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  es return one of
6e10: 20 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b   30 integer.** [
6e20: 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20  result codes].  
6e30: 48 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65  However, experie
6e40: 6e 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68  nce has shown th
6e50: 61 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68  at many of.** th
6e60: 65 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ese result codes
6e70: 20 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d   are too coarse-
6e80: 67 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64  grained.  They d
6e90: 6f 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73  o not provide as
6ea0: 0a 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61  .** much informa
6eb0: 74 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c  tion about probl
6ec0: 65 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65  ems as programme
6ed0: 72 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20  rs might like.  
6ee0: 49 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a  In an effort to.
6ef0: 2a 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c  ** address this,
6f00: 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20   newer versions 
6f10: 6f 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69  of SQLite (versi
6f20: 6f 6e 20 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74  on 3.3.8 and lat
6f30: 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73  er) include.** s
6f40: 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69 74  upport for addit
6f50: 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f 64  ional result cod
6f60: 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65 20  es that provide 
6f70: 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69 6e  more detailed in
6f80: 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f  formation.** abo
6f90: 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73 65  ut errors. These
6fa0: 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
6fb0: 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e 61  t codes] are ena
6fc0: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
6fd0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
6fe0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
6ff0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
7000: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
7010: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
7020: 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c 20  es()] API.  Or, 
7030: 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f 64  the extended cod
7040: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f 73  e for.** the mos
7050: 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20 63  t recent error c
7060: 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 75  an be obtained u
7070: 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
7080: 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
7090: 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  e()]..*/.#define
70a0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45   SQLITE_IOERR_RE
70b0: 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AD              
70c0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
70d0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
70e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
70f0: 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28  RT_READ        (
7100: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
7110: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
7120: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54  QLITE_IOERR_WRIT
7130: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  E             (S
7140: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33  QLITE_IOERR | (3
7150: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
7160: 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43  LITE_IOERR_FSYNC
7170: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
7180: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c  LITE_IOERR | (4<
7190: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
71a0: 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53  ITE_IOERR_DIR_FS
71b0: 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c  YNC         (SQL
71c0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c  ITE_IOERR | (5<<
71d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
71e0: 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54  TE_IOERR_TRUNCAT
71f0: 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  E          (SQLI
7200: 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38  TE_IOERR | (6<<8
7210: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7220: 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20  E_IOERR_FSTAT   
7230: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
7240: 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29  E_IOERR | (7<<8)
7250: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
7260: 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20  _IOERR_UNLOCK   
7270: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
7280: 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29  _IOERR | (8<<8))
7290: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
72a0: 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20  IOERR_RDLOCK    
72b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
72c0: 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a  IOERR | (9<<8)).
72d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
72e0: 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20  OERR_DELETE     
72f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7300: 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a  OERR | (10<<8)).
7310: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7320: 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20  OERR_BLOCKED    
7330: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7340: 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a  OERR | (11<<8)).
7350: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7360: 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20  OERR_NOMEM      
7370: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7380: 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a  OERR | (12<<8)).
7390: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
73a0: 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20  OERR_ACCESS     
73b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
73c0: 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a  OERR | (13<<8)).
73d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
73e0: 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56  OERR_CHECKRESERV
73f0: 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49  EDLOCK (SQLITE_I
7400: 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a  OERR | (14<<8)).
7410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7420: 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20  OERR_LOCK       
7430: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7440: 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a  OERR | (15<<8)).
7450: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7460: 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  OERR_CLOSE      
7470: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7480: 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a  OERR | (16<<8)).
7490: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
74a0: 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20  OERR_DIR_CLOSE  
74b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
74c0: 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a  OERR | (17<<8)).
74d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
74e0: 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20  OERR_SHMOPEN    
74f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7500: 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a  OERR | (18<<8)).
7510: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7520: 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20  OERR_SHMSIZE    
7530: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7540: 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a  OERR | (19<<8)).
7550: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7560: 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20  OERR_SHMLOCK    
7570: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7580: 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a  OERR | (20<<8)).
7590: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
75a0: 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20  OERR_SHMMAP     
75b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
75c0: 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a  OERR | (21<<8)).
75d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
75e0: 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20  OERR_SEEK       
75f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7600: 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a  OERR | (22<<8)).
7610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7620: 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e  OERR_DELETE_NOEN
7630: 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49  T      (SQLITE_I
7640: 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a  OERR | (23<<8)).
7650: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
7660: 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20 20  OERR_MMAP       
7670: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7680: 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29 0a  OERR | (24<<8)).
7690: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
76a0: 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54 48  OERR_GETTEMPPATH
76b0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
76c0: 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29 0a  OERR | (25<<8)).
76d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
76e0: 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20 20  OERR_CONVPATH   
76f0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
7700: 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29 0a  OERR | (26<<8)).
7710: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
7720: 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48  OCKED_SHAREDCACH
7730: 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c  E      (SQLITE_L
7740: 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29  OCKED |  (1<<8))
7750: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
7760: 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20  BUSY_RECOVERY   
7770: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
7780: 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29  BUSY   |  (1<<8)
7790: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
77a0: 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20 20  _BUSY_SNAPSHOT  
77b0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
77c0: 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c 38  _BUSY   |  (2<<8
77d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
77e0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d  E_CANTOPEN_NOTEM
77f0: 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54  PDIR      (SQLIT
7800: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c  E_CANTOPEN | (1<
7810: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
7820: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44  ITE_CANTOPEN_ISD
7830: 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  IR          (SQL
7840: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
7850: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
7860: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46  QLITE_CANTOPEN_F
7870: 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28 53  ULLPATH       (S
7880: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c  QLITE_CANTOPEN |
7890: 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (3<<8)).#define
78a0: 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e   SQLITE_CANTOPEN
78b0: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
78c0: 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  (SQLITE_CANTOPEN
78d0: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
78e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  ne SQLITE_CORRUP
78f0: 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20 20  T_VTAB          
7900: 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55 50    (SQLITE_CORRUP
7910: 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  T | (1<<8)).#def
7920: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
7930: 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  NLY_RECOVERY    
7940: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
7950: 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  NLY | (1<<8)).#d
7960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
7970: 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20 20  DONLY_CANTLOCK  
7980: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
7990: 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29 0a  DONLY | (2<<8)).
79a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
79b0: 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b  EADONLY_ROLLBACK
79c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52         (SQLITE_R
79d0: 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38 29  EADONLY | (3<<8)
79e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
79f0: 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45  _READONLY_DBMOVE
7a00: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
7a10: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c  _READONLY | (4<<
7a20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
7a30: 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43  TE_ABORT_ROLLBAC
7a40: 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  K          (SQLI
7a50: 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38  TE_ABORT | (2<<8
7a60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7a70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48 45  E_CONSTRAINT_CHE
7a80: 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  CK        (SQLIT
7a90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
7aa0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
7ab0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7ac0: 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28 53  _COMMITHOOK   (S
7ad0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7ae0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
7af0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
7b00: 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59 20  AINT_FOREIGNKEY 
7b10: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
7b20: 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a 23  AINT | (3<<8)).#
7b30: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7b40: 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49 4f  NSTRAINT_FUNCTIO
7b50: 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  N     (SQLITE_CO
7b60: 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c 38  NSTRAINT | (4<<8
7b70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7b80: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f 54  E_CONSTRAINT_NOT
7b90: 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49 54  NULL      (SQLIT
7ba0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
7bb0: 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  5<<8)).#define S
7bc0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7bd0: 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28 53  _PRIMARYKEY   (S
7be0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7bf0: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
7c00: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
7c10: 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20 20  AINT_TRIGGER    
7c20: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
7c30: 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a 23  AINT | (7<<8)).#
7c40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
7c50: 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45 20  NSTRAINT_UNIQUE 
7c60: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
7c70: 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c 38  NSTRAINT | (8<<8
7c80: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
7c90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54 41  E_CONSTRAINT_VTA
7ca0: 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  B         (SQLIT
7cb0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
7cc0: 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  9<<8)).#define S
7cd0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7ce0: 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28 53  _ROWID        (S
7cf0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
7d00: 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69   |(10<<8)).#defi
7d10: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
7d20: 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20 20  _RECOVER_WAL    
7d30: 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45    (SQLITE_NOTICE
7d40: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
7d50: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  ne SQLITE_NOTICE
7d60: 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41 43  _RECOVER_ROLLBAC
7d70: 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45  K (SQLITE_NOTICE
7d80: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
7d90: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
7da0: 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20 20  G_AUTOINDEX     
7db0: 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e    (SQLITE_WARNIN
7dc0: 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  G | (1<<8)).#def
7dd0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 5f  ine SQLITE_AUTH_
7de0: 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20 20  USER            
7df0: 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48 20     (SQLITE_AUTH 
7e00: 7c 20 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a  | (1<<8))../*.**
7e10: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
7e20: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f   For File Open O
7e30: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  perations.**.** 
7e40: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
7e50: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
7e60: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
7e70: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
7e80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
7e90: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
7ea0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
7eb0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
7ec0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
7ed0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
7ee0: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
7ef0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
7f00: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
7f10: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
7f20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
7f30: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
7f40: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
7f50: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
7f60: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
7f70: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
7f80: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
7f90: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
7fa0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
7fb0: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
7fc0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
7fd0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
7fe0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
7ff0: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
8000: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
8010: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
8020: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
8030: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
8040: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
8050: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
8060: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f  ITE_OPEN_AUTOPRO
8070: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30  XY        0x0000
8080: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0020  /* VFS onl
8090: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
80a0: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20  ITE_OPEN_URI    
80b0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
80c0: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0040  /* Ok for 
80d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
80e0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
80f0: 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20  ITE_OPEN_MEMORY 
8100: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
8110: 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0080  /* Ok for 
8120: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
8130: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
8140: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
8150: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
8160: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
8170: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
8180: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
8190: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
81a0: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
81b0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
81c0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
81d0: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
81e0: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
81f0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
8200: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
8210: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
8220: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
8230: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
8240: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
8250: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
8260: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
8270: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
8280: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
8290: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
82a0: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
82b0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
82c0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
82d0: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
82e0: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
82f0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
8300: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
8310: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
8320: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
8330: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
8340: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
8350: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
8360: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
8370: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
8380: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
8390: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
83a0: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
83b0: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32  ACHE      0x0002
83c0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
83d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
83e0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
83f0: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
8400: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34  CACHE     0x0004
8410: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
8420: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
8430: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
8440: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20  ITE_OPEN_WAL    
8450: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38            0x0008
8460: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0000  /* VFS onl
8470: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65  y */../* Reserve
8480: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  d:              
8490: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46             0x00F
84a0: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  00000 */../*.** 
84b0: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
84c0: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
84d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
84e0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
84f0: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
8500: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
8510: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
8520: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
8530: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
8540: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  tor of these.** 
8550: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
8560: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
8570: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
8580: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
8590: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
85a0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
85b0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
85c0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
85d0: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
85e0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
85f0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
8600: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
8610: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
8620: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
8630: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
8640: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
8650: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
8660: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
8670: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
8680: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
8690: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
86a0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
86b0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
86c0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
86d0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
86e0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
86f0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
8700: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
8710: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
8720: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
8730: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
8740: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
8750: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
8760: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
8770: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
8780: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
8790: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
87a0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
87b0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
87c0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
87d0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
87e0: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
87f0: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
8800: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
8810: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
8820: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
8830: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
8840: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
8850: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
8860: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
8870: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
8880: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
8890: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
88a0: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
88b0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
88c0: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
88d0: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
88e0: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
88f0: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
8900: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
8910: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
8920: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
8930: 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
8940: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
8950: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
8960: 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63  EN.** flag indic
8970: 61 74 65 20 74 68 61 74 20 61 20 66 69 6c 65 20  ate that a file 
8980: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
8990: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
89a0: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
89b0: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
89c0: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
89d0: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
89e0: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
89f0: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
8a00: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
8a10: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
8a20: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
8a30: 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  leges..*/.#defin
8a40: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
8a50: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
8a60: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
8a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8a80: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
8a90: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
8aa0: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
8ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8ac0: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20  MIC1K           
8ad0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
8ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
8af0: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
8b00: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
8b10: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
8b20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8b30: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C4K             
8b40: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
8b50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
8b60: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
8b70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
8b80: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
8b90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
8ba0: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  6K              
8bb0: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
8bc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
8bd0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
8be0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
8bf0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
8c00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
8c10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
8c20: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
8c30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
8c40: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20  FE_APPEND       
8c50: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
8c60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8c70: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
8c80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
8c90: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
8ca0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
8cb0: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
8cc0: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64  N  0x00000800.#d
8cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
8ce0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
8cf0: 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30  RWRITE    0x0000
8d00: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
8d10: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
8d20: 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  BLE             
8d30: 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a   0x00002000../*.
8d40: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
8d50: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
8d60: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
8d70: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
8d80: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
8d90: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
8da0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
8db0: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
8dc0: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
8dd0: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
8de0: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
8df0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
8e00: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
8e10: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
8e20: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
8e30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
8e40: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
8e50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8e60: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
8e70: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
8e80: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
8e90: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
8ea0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
8eb0: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
8ec0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
8ed0: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
8ee0: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
8ef0: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
8f00: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
8f10: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
8f20: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8f30: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
8f40: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
8f50: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
8f60: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
8f70: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
8f80: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
8f90: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
8fa0: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
8fb0: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
8fc0: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
8fd0: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
8fe0: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
8ff0: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
9000: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
9010: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
9020: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
9030: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
9040: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
9050: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
9060: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
9070: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
9080: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
9090: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
90a0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
90b0: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
90c0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
90d0: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
90e0: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
90f0: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
9100: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
9110: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
9120: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
9130: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
9140: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
9150: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
9160: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
9170: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
9180: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
9190: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
91a0: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
91b0: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
91c0: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
91d0: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
91e0: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
91f0: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
9200: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
9210: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
9220: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
9230: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
9240: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
9250: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
9260: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
9270: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
9280: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
9290: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
92a0: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
92b0: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
92c0: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
92d0: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
92e0: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
92f0: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
9300: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
9310: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
9320: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
9330: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
9340: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
9350: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
9360: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
9370: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
9380: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
9390: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
93a0: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
93b0: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
93c0: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
93d0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
93e0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
93f0: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
9400: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
9410: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
9420: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
9430: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
9440: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
9450: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
9460: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
9470: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
9480: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
9490: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
94a0: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
94b0: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
94c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
94d0: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
94e0: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
94f0: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
9500: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
9510: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
9520: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
9530: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
9540: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
9550: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
9560: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
9570: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
9580: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
9590: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
95a0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
95b0: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
95c0: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
95d0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
95e0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
95f0: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
9600: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
9610: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
9620: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
9630: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
9640: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
9650: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
9660: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
9670: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
9680: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
9690: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
96a0: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
96b0: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
96c0: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
96d0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
96e0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
96f0: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
9700: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
9710: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
9720: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
9730: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
9740: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
9750: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9760: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
9770: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
9780: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
9790: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
97a0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
97b0: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
97c0: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
97d0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
97e0: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
97f0: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
9800: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
9810: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
9820: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
9830: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
9840: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
9850: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
9860: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
9870: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
9880: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
9890: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
98a0: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
98b0: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
98c0: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
98d0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
98e0: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
98f0: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
9900: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
9910: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
9920: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
9930: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
9940: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
9950: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
9960: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
9970: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
9980: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
9990: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
99a0: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
99b0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
99c0: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
99d0: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
99e0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
99f0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
9a00: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
9a10: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
9a20: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
9a30: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
9a40: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
9a50: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
9a60: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
9a70: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
9a80: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
9a90: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
9aa0: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
9ab0: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
9ac0: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
9ad0: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
9ae0: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
9af0: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
9b00: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
9b10: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
9b20: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
9b30: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
9b40: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
9b50: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
9b60: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
9b70: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
9b80: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
9b90: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
9ba0: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
9bb0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
9bc0: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
9bd0: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
9be0: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
9bf0: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
9c00: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
9c10: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
9c20: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
9c30: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
9c40: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
9c50: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
9c60: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
9c70: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
9c80: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
9c90: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
9ca0: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
9cb0: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
9cc0: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
9cd0: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
9ce0: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
9cf0: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
9d00: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
9d10: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
9d20: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
9d30: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
9d40: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
9d50: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
9d60: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
9d70: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
9d80: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
9d90: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
9da0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
9db0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
9dc0: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
9dd0: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
9de0: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
9df0: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
9e00: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
9e10: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
9e20: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
9e30: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
9e40: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
9e50: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
9e60: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
9e70: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
9e80: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
9e90: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
9ea0: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
9eb0: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
9ec0: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
9ed0: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
9ee0: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
9ef0: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
9f00: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
9f10: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
9f20: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
9f30: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
9f40: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
9f50: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
9f60: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
9f70: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
9f80: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
9f90: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
9fa0: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
9fb0: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
9fc0: 0a 2a 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74  .** A [file cont
9fd0: 72 6f 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69  rol opcodes | li
9fe0: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
9ff0: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
a000: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
a010: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
a020: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
a030: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
a040: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
a050: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
a060: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
a070: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20  oid conflicts.  
a080: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
a090: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ons should.** re
a0a0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  turn [SQLITE_NOT
a0b0: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20  FOUND] for file 
a0c0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
a0d0: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
a0e0: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a  .** recognize..*
a0f0: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
a100: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
a110: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
a120: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
a130: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
a140: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
a150: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
a160: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
a170: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
a180: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
a190: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
a1a0: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
a1b0: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
a1c0: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
a1d0: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
a1e0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
a1f0: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
a200: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
a210: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
a220: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
a230: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
a240: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
a250: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
a260: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
a270: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
a280: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a290: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
a2a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a2b0: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
a2c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a2d0: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
a2e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a2f0: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
a300: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
a310: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
a320: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
a330: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
a340: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
a350: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
a360: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
a370: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
a380: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
a390: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
a3a0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
a3b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
a3c0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
a3d0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
a3e0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
a3f0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
a400: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
a410: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
a420: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
a430: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
a440: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
a450: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
a460: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
a470: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
a480: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
a490: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
a4a0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
a4b0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
a4c0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
a4d0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
a4e0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
a4f0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
a500: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
a510: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
a520: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
a530: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
a540: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
a550: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
a560: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
a570: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
a580: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
a590: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
a5a0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
a5b0: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
a5c0: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
a5d0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
a5e0: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52  e()..**.** If xR
a5f0: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51  ead() returns SQ
a600: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
a610: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c  _READ it must al
a620: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68  so fill.** in th
a630: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e  e unread portion
a640: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  s of the buffer 
a650: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56  with zeros.  A V
a660: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73  FS that.** fails
a670: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
a680: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20  ort reads might 
a690: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48  seem to work.  H
a6a0: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75  owever,.** failu
a6b0: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  re to zero-fill 
a6c0: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c  short reads will
a6d0: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64   eventually lead
a6e0: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   to.** database 
a6f0: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74  corruption..*/.t
a700: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
a710: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
a720: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
a730: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
a740: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b  te3_io_methods {
a750: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
a760: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
a770: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
a780: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28  .  int (*xRead)(
a790: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76  sqlite3_file*, v
a7a0: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
a7b0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
a7c0: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57  fst);.  int (*xW
a7d0: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  rite)(sqlite3_fi
a7e0: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  le*, const void*
a7f0: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
a800: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
a810: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63  ;.  int (*xTrunc
a820: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ate)(sqlite3_fil
a830: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
a840: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  4 size);.  int (
a850: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
a860: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73  file*, int flags
a870: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
a880: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
a890: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
a8a0: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e  64 *pSize);.  in
a8b0: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74  t (*xLock)(sqlit
a8c0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
a8d0: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29    int (*xUnlock)
a8e0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
a8f0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  int);.  int (*xC
a900: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
a910: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
a920: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
a930: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e    int (*xFileCon
a940: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69  trol)(sqlite3_fi
a950: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  le*, int op, voi
a960: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  d *pArg);.  int 
a970: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73  (*xSectorSize)(s
a980: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
a990: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68   int (*xDeviceCh
a9a0: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73  aracteristics)(s
a9b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
a9c0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
a9d0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
a9e0: 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69  version 1 */.  i
a9f0: 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71  nt (*xShmMap)(sq
aa00: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
aa10: 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20   iPg, int pgsz, 
aa20: 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69  int, void volati
aa30: 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  le**);.  int (*x
aa40: 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  ShmLock)(sqlite3
aa50: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73  _file*, int offs
aa60: 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66  et, int n, int f
aa70: 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a  lags);.  void (*
aa80: 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c  xShmBarrier)(sql
aa90: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
aaa0: 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28  nt (*xShmUnmap)(
aab0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
aac0: 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a  nt deleteFlag);.
aad0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
aae0: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
aaf0: 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20   version 2 */.  
ab00: 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28 73 71  int (*xFetch)(sq
ab10: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
ab20: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
ab30: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64  , int iAmt, void
ab40: 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a   **pp);.  int (*
ab50: 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65  xUnfetch)(sqlite
ab60: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
ab70: 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f  _int64 iOfst, vo
ab80: 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74  id *p);.  /* Met
ab90: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
aba0: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
abb0: 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74   3 */.  /* Addit
abc0: 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61  ional methods ma
abd0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
abe0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f  ture releases */
abf0: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
ac00: 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69  REF: Standard Fi
ac10: 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64  le Control Opcod
ac20: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
ac30: 7b 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70  {file control op
ac40: 63 6f 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e  codes} {file con
ac50: 74 72 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a  trol opcode}.**.
ac60: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
ac70: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f   constants are o
ac80: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78  pcodes for the x
ac90: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
aca0: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  od.** of the [sq
acb0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
acc0: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72  ] object and for
acd0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
ace0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a  le_control()].**
acf0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
ad00: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
ad10: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
ad20: 4b 53 54 41 54 45 5d 5d 0a 2a 2a 20 54 68 65 20  KSTATE]].** The 
ad30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f  [SQLITE_FCNTL_LO
ad40: 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20  CKSTATE] opcode 
ad50: 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75  is used for debu
ad60: 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20  gging.  This.** 
ad70: 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68  opcode causes th
ad80: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
ad90: 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74  ethod to write t
ada0: 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65  he current state
adb0: 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20   of.** the lock 
adc0: 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f  (one of [SQLITE_
add0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c  LOCK_NONE], [SQL
ade0: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d  ITE_LOCK_SHARED]
adf0: 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ,.** [SQLITE_LOC
ae00: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51  K_RESERVED], [SQ
ae10: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
ae20: 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c  G], or [SQLITE_L
ae30: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a  OCK_EXCLUSIVE]).
ae40: 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67  ** into an integ
ae50: 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67  er that the pArg
ae60: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
ae70: 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69   to. This capabi
ae80: 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20  lity.** is used 
ae90: 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61  during testing a
aea0: 6e 64 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c  nd is only avail
aeb0: 61 62 6c 65 20 77 68 65 6e 20 74 68 65 20 53 51  able when the SQ
aec0: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 63 6f 6d  LITE_TEST.** com
aed0: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
aee0: 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
aef0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
af00: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a  TL_SIZE_HINT]].*
af10: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
af20: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f  NTL_SIZE_HINT] o
af30: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62 79  pcode is used by
af40: 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20   SQLite to give 
af50: 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72  the VFS.** layer
af60: 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c   a hint of how l
af70: 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61 73  arge the databas
af80: 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77  e file will grow
af90: 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68   to be during th
afa0: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61  e.** current tra
afb0: 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20  nsaction.  This 
afc0: 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72  hint is not guar
afd0: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63 63  anteed to be acc
afe0: 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20  urate but it.** 
aff0: 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20  is often close. 
b000: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
b010: 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65  VFS might choose
b020: 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20   to preallocate 
b030: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
b040: 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20   space based on 
b050: 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64  this hint in ord
b060: 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65  er to help write
b070: 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  s to the databas
b080: 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61  e.** file run fa
b090: 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ster..**.** <li>
b0a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  [[SQLITE_FCNTL_C
b0b0: 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54  HUNK_SIZE]].** T
b0c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b0d0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63  _CHUNK_SIZE] opc
b0e0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 72  ode is used to r
b0f0: 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65 20  equest that the 
b100: 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61  VFS.** extends a
b110: 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68 65  nd truncates the
b120: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
b130: 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69  n chunks of a si
b140: 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ze specified.** 
b150: 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68 65  by the user. The
b160: 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
b170: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   to [sqlite3_fil
b180: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f  e_control()] sho
b190: 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  uld .** point to
b1a0: 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70   an integer (typ
b1b0: 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e  e int) containin
b1c0: 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d  g the new chunk-
b1d0: 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66  size to use.** f
b1e0: 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64  or the nominated
b1f0: 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63   database. Alloc
b200: 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 66  ating database f
b210: 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72  ile space in lar
b220: 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61  ge.** chunks (sa
b230: 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29  y 1MB at a time)
b240: 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c  , may reduce fil
b250: 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e  e-system fragmen
b260: 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d  tation and.** im
b270: 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
b280: 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d  e on some system
b290: 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  s..**.** <li>[[S
b2a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
b2b0: 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68  _POINTER]].** Th
b2c0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
b2d0: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  FILE_POINTER] op
b2e0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
b2f0: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
b300: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
b310: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
b320: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
b330: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
b340: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
b350: 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b  tion.  See the [
b360: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
b370: 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74  trol()] document
b380: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64  ation for.** add
b390: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
b3a0: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
b3b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
b3c0: 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20  NC_OMITTED]].** 
b3d0: 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65  No longer in use
b3e0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
b3f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d  LITE_FCNTL_SYNC]
b400: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
b410: 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63  _FCNTL_SYNC] opc
b420: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
b430: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 53   internally by S
b440: 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e  QLite and.** sen
b450: 74 20 74 6f 20 74 68 65 20 56 46 53 20 69 6d 6d  t to the VFS imm
b460: 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72 65 20  ediately before 
b470: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
b480: 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61   is invoked on a
b490: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66 69 6c  .** database fil
b4a0: 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20 4f 72  e descriptor. Or
b4b0: 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63 20 6d  , if the xSync m
b4c0: 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76  ethod is not inv
b4d0: 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75 73 65  oked .** because
b4e0: 20 74 68 65 20 75 73 65 72 20 68 61 73 20 63 6f   the user has co
b4f0: 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74 65 20  nfigured SQLite 
b500: 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  with .** [PRAGMA
b510: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50   synchronous | P
b520: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
b530: 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69 6e 76  s=OFF] it is inv
b540: 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a  oked in place .*
b550: 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63 20 6d  * of the xSync m
b560: 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63  ethod. In most c
b570: 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e 74 65  ases, the pointe
b580: 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  r argument passe
b590: 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73 20 66  d with.** this f
b5a0: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e  ile-control is N
b5b0: 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20 69 66  ULL. However, if
b5c0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
b5d0: 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79 6e 63  le is being sync
b5e0: 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66  ed.** as part of
b5f0: 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62 61 73   a multi-databas
b600: 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72  e commit, the ar
b610: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
b620: 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65   a nul-terminate
b630: 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74  d.** string cont
b640: 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61 6e 73  aining the trans
b650: 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a  actions master-j
b660: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65  ournal file name
b670: 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a 2a 2a  . VFSes that .**
b680: 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69   do not need thi
b690: 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20  s signal should 
b6a0: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
b6b0: 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70 70  this opcode. App
b6c0: 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68  lications .** sh
b6d0: 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73  ould not call [s
b6e0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
b6f0: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
b700: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
b710: 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72   so may .** disr
b720: 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f  upt the operatio
b730: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
b740: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20  ized VFSes that 
b750: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
b760: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b770: 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54  ITE_FCNTL_COMMIT
b780: 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54  _PHASETWO]].** T
b790: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
b7a0: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
b7b0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
b7c0: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
b7d0: 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
b7e0: 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46  d sent to the VF
b7f0: 53 20 61 66 74 65 72 20 61 20 74 72 61 6e 73 61  S after a transa
b800: 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 63  ction has been c
b810: 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64 69 61  ommitted immedia
b820: 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f  tely.** but befo
b830: 72 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  re the database 
b840: 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53  is unlocked. VFS
b850: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e  es that do not n
b860: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 0a  eed this signal.
b870: 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  ** should silent
b880: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
b890: 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61 74 69  pcode. Applicati
b8a0: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
b8b0: 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  all.** [sqlite3_
b8c0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
b8d0: 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65  with this opcode
b8e0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
b8f0: 20 64 69 73 72 75 70 74 20 74 68 65 20 0a 2a 2a   disrupt the .**
b900: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
b910: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
b920: 53 65 73 20 74 68 61 74 20 64 6f 20 72 65 71 75  Ses that do requ
b930: 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20  ire it.  .**.** 
b940: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
b950: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
b960: 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  Y]].** ^The [SQL
b970: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b980: 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65  AV_RETRY] opcode
b990: 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66   is used to conf
b9a0: 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a  igure automatic.
b9b0: 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20  ** retry counts 
b9c0: 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f  and intervals fo
b9d0: 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49  r certain disk I
b9e0: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f  /O operations fo
b9f0: 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73  r the.** windows
ba00: 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20   [VFS] in order 
ba10: 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73  to provide robus
ba20: 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65  tness in the pre
ba30: 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69  sence of.** anti
ba40: 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e  -virus programs.
ba50: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
ba60: 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69  e windows VFS wi
ba70: 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65  ll retry file re
ba80: 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74  ad,.** file writ
ba90: 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65  e, and file dele
baa0: 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70  te operations up
bab0: 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69   to 10 times, wi
bac0: 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66  th a delay.** of
bad0: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
bae0: 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73   before the firs
baf0: 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68  t retry and with
bb00: 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65   the delay incre
bb10: 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61  asing.** by an a
bb20: 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c  dditional 25 mil
bb30: 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65  liseconds with e
bb40: 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72  ach subsequent r
bb50: 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  etry.  This.** o
bb60: 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65  pcode allows the
bb70: 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31  se two values (1
bb80: 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35  0 retries and 25
bb90: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
bba0: 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65   delay).** to be
bbb0: 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20   adjusted.  The 
bbc0: 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67  values are chang
bbd0: 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62  ed for all datab
bbe0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  ase connections.
bbf0: 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  ** within the sa
bc00: 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65  me process.  The
bc10: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
bc20: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72  ointer to an arr
bc30: 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74  ay of two.** int
bc40: 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20  egers where the 
bc50: 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20  first integer i 
bc60: 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f  the new retry co
bc70: 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  unt and the seco
bc80: 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73  nd.** integer is
bc90: 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20   the delay.  If 
bca0: 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69  either integer i
bcb0: 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
bcc0: 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20   the setting.** 
bcd0: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62  is not changed b
bce0: 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70  ut instead the p
bcf0: 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
bd00: 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72  at setting is wr
bd10: 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68  itten.** into th
bd20: 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61  e array entry, a
bd30: 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72  llowing the curr
bd40: 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e  ent retry settin
bd50: 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65  gs to be.** inte
bd60: 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a  rrogated.  The z
bd70: 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  DbName parameter
bd80: 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
bd90: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
bda0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
bdb0: 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  L]].** ^The [SQL
bdc0: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
bdd0: 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73  T_WAL] opcode is
bde0: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
bdf0: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
be00: 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57  sistent [WAL | W
be10: 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20  rite Ahead Log] 
be20: 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66  setting.  By def
be30: 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69  ault, the auxili
be40: 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65  ary.** write ahe
be50: 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65  ad log and share
be60: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75  d memory files u
be70: 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74  sed for transact
be80: 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61  ion control.** a
be90: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
bea0: 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68   deleted when th
beb0: 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74  e latest connect
bec0: 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62  ion to the datab
bed0: 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20  ase.** closes.  
bee0: 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65  Setting persiste
bef0: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73  nt WAL mode caus
bf00: 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74  es those files t
bf10: 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a  o persist after.
bf20: 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69  ** close.  Persi
bf30: 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20  sting the files 
bf40: 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f  is useful when o
bf50: 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74  ther processes t
bf60: 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61  hat do not.** ha
bf70: 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73  ve write permiss
bf80: 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63  ion on the direc
bf90: 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  tory containing 
bfa0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
bfb0: 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61  e want.** to rea
bfc0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  d the database f
bfd0: 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20  ile, as the WAL 
bfe0: 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72  and shared memor
bff0: 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69  y files must exi
c000: 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66  st.** in order f
c010: 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
c020: 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20  to be readable. 
c030: 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   The fourth para
c040: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  meter to.** [sql
c050: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
c060: 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70  l()] for this op
c070: 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61  code should be a
c080: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
c090: 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20  nteger..** That 
c0a0: 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20  integer is 0 to 
c0b0: 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65  disable persiste
c0c0: 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31  nt WAL mode or 1
c0d0: 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69   to enable persi
c0e0: 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64  stent.** WAL mod
c0f0: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
c100: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
c110: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
c120: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
c130: 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74  t.** WAL persist
c140: 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  ence setting..**
c150: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
c160: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
c170: 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20  _OVERWRITE]].** 
c180: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
c190: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
c1a0: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
c1b0: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
c1c0: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
c1d0: 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73  rsistent "powers
c1e0: 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f  afe-overwrite" o
c1f0: 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67  r "PSOW" setting
c200: 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74  .  The PSOW sett
c210: 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65  ing.** determine
c220: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f  s the [SQLITE_IO
c230: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
c240: 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20  ERWRITE] bit of 
c250: 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68  the.** xDeviceCh
c260: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
c270: 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74  thods. The fourt
c280: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  h parameter to.*
c290: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
c2a0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74  control()] for t
c2b0: 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c  his opcode shoul
c2c0: 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  d be a pointer t
c2d0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  o an integer..**
c2e0: 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73   That integer is
c2f0: 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65   0 to disable ze
c300: 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f  ro-damage mode o
c310: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65  r 1 to enable ze
c320: 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64  ro-damage.** mod
c330: 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67  e.  If the integ
c340: 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69  er is -1, then i
c350: 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  t is overwritten
c360: 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
c370: 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65  t.** zero-damage
c380: 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a   mode setting..*
c390: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
c3a0: 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54  E_FCNTL_OVERWRIT
c3b0: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
c3c0: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
c3d0: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69  ITE] opcode is i
c3e0: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
c3f0: 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a   after opening.*
c400: 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61  * a write transa
c410: 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74  ction to indicat
c420: 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69  e that, unless i
c430: 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t is rolled back
c440: 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61   for some.** rea
c450: 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20  son, the entire 
c460: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
c470: 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ll be overwritte
c480: 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  n by the current
c490: 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e   .** transaction
c4a0: 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62  . This is used b
c4b0: 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69  y VACUUM operati
c4c0: 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ons..**.** <li>[
c4d0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
c4e0: 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  SNAME]].** ^The 
c4f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46  [SQLITE_FCNTL_VF
c500: 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61  SNAME] opcode ca
c510: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
c520: 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
c530: 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20  .** all [VFSes] 
c540: 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b  in the VFS stack
c550: 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65  .  The names are
c560: 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d   of all VFS shim
c570: 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e  s and the.** fin
c580: 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20  al bottom-level 
c590: 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20  VFS are written 
c5a0: 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
c5b0: 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
c5c0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
c5d0: 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20   and the result 
c5e0: 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65  is stored in the
c5f0: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a   char* variable.
c600: 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72  ** that the four
c610: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  th parameter of 
c620: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
c630: 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20  ntrol()] points 
c640: 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65  to..** The calle
c650: 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  r is responsible
c660: 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65   for freeing the
c670: 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e   memory when don
c680: 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61  e.  As with.** a
c690: 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ll file-control 
c6a0: 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69  actions, there i
c6b0: 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74  s no guarantee t
c6c0: 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63  hat this will ac
c6d0: 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79  tually.** do any
c6e0: 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20  thing.  Callers 
c6f0: 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a  should initializ
c700: 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  e the char* vari
c710: 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a  able to a NULL.*
c720: 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73  * pointer in cas
c730: 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74  e this file-cont
c740: 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  rol is not imple
c750: 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69  mented.  This fi
c760: 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73  le-control.** is
c770: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69   intended for di
c780: 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c  agnostic use onl
c790: 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  y..**.** <li>[[S
c7a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
c7b0: 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65  MA]].** ^Wheneve
c7c0: 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  r a [PRAGMA] sta
c7d0: 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64  tement is parsed
c7e0: 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e  , an [SQLITE_FCN
c7f0: 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66  TL_PRAGMA] .** f
c800: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73  ile control is s
c810: 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20  ent to the open 
c820: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
c830: 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64  bject correspond
c840: 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61  ing.** to the da
c850: 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77  tabase file to w
c860: 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20  hich the pragma 
c870: 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73  statement refers
c880: 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a  . ^The argument.
c890: 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54  ** to the [SQLIT
c8a0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
c8b0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
c8c0: 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70  an array of.** p
c8d0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
c8e0: 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77  gs (char**) in w
c8f0: 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20  hich the second 
c900: 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  element of the a
c910: 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e  rray.** is the n
c920: 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d  ame of the pragm
c930: 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20  a and the third 
c940: 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61  element is the a
c950: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a  rgument to the.*
c960: 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c  * pragma or NULL
c970: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68   if the pragma h
c980: 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20  as no argument. 
c990: 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f   ^The handler fo
c9a0: 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r an.** [SQLITE_
c9b0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
c9c0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f  le control can o
c9d0: 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74  ptionally make t
c9e0: 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74  he first element
c9f0: 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a  .** of the char*
ca00: 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  * argument point
ca10: 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74   to a string obt
ca20: 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
ca30: 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a  te3_mprintf()].*
ca40: 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c  * or the equival
ca50: 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72  ent and that str
ca60: 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20  ing will become 
ca70: 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68  the result of th
ca80: 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74  e pragma or.** t
ca90: 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
caa0: 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66   if the pragma f
cab0: 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a  ails. ^If the.**
cac0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
cad0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
cae0: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
caf0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
cb00: 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b  hen normal .** [
cb10: 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69  PRAGMA] processi
cb20: 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e  ng continues.  ^
cb30: 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  If the [SQLITE_F
cb40: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
cb50: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
cb60: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
cb70: 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65  , then the parse
cb80: 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  r assumes that t
cb90: 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61  he.** VFS has ha
cba0: 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41  ndled the PRAGMA
cbb0: 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20   itself and the 
cbc0: 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73  parser generates
cbd0: 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70   a no-op.** prep
cbe0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69  ared statement i
cbf0: 66 20 72 65 73 75 6c 74 20 73 74 72 69 6e 67 20  f result string 
cc00: 69 73 20 4e 55 4c 4c 2c 20 6f 72 20 74 68 61 74  is NULL, or that
cc10: 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 0a   returns a copy.
cc20: 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  ** of the result
cc30: 20 73 74 72 69 6e 67 20 69 66 20 74 68 65 20 73   string if the s
cc40: 74 72 69 6e 67 20 69 73 20 6e 6f 6e 2d 4e 55 4c  tring is non-NUL
cc50: 4c 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  L..** ^If the [S
cc60: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
cc70: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
cc80: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
cc90: 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65  result code othe
cca0: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
ccb0: 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f  K] or [SQLITE_NO
ccc0: 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65  TFOUND], that me
ccd0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ans.** that the 
cce0: 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  VFS encountered 
ccf0: 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68  an error while h
cd00: 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41  andling the [PRA
cd10: 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  GMA] and the.** 
cd20: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74  compilation of t
cd30: 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20  he PRAGMA fails 
cd40: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
cd50: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
cd60: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
cd70: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72  le control occur
cd80: 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69  s at the beginni
cd90: 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61  ng of pragma sta
cda0: 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20  tement analysis 
cdb0: 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20  and so.** it is 
cdc0: 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65  able to override
cdd0: 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d   built-in [PRAGM
cde0: 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  A] statements..*
cdf0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
ce00: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
ce10: 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  LER]].** ^The [S
ce20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
ce30: 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65  HANDLER].** file
ce40: 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20  -control may be 
ce50: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
ce60: 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  e on the databas
ce70: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a  e file handle.**
ce80: 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69   shortly after i
ce90: 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f  t is opened in o
cea0: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
ceb0: 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74  a custom VFS wit
cec0: 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74  h access.** to t
ced0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62  he connections b
cee0: 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
cef0: 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65  back. The argume
cf00: 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76  nt is of type (v
cf10: 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20  oid **).** - an 
cf20: 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f  array of two (vo
cf30: 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68  id *) values. Th
cf40: 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29  e first (void *)
cf50: 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73   actually points
cf60: 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  .** to a functio
cf70: 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28  n of type (int (
cf80: 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20  *)(void *)). In 
cf90: 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20  order to invoke 
cfa0: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  the connections.
cfb0: 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c  ** busy-handler,
cfc0: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73   this function s
cfd0: 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64  hould be invoked
cfe0: 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64   with the second
cff0: 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20   (void *) in.** 
d000: 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65  the array as the
d010: 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20   only argument. 
d020: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f  If it returns no
d030: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
d040: 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68   operation.** sh
d050: 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e  ould be retried.
d060: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a   If it returns z
d070: 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20  ero, the custom 
d080: 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64  VFS should aband
d090: 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  on the.** curren
d0a0: 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  t operation..**.
d0b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
d0c0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
d0d0: 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61  ME]].** ^Applica
d0e0: 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20  tion can invoke 
d0f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
d100: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20  L_TEMPFILENAME] 
d110: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
d120: 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67  to have SQLite g
d130: 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d  enerate a.** tem
d140: 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20  porary filename 
d150: 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61  using the same a
d160: 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73  lgorithm that is
d170: 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e   followed to gen
d180: 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  erate.** tempora
d190: 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72  ry filenames for
d1a0: 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64   TEMP tables and
d1b0: 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20   other internal 
d1c0: 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72  uses.  The.** ar
d1d0: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
d1e0: 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20   a char** which 
d1f0: 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77  will be filled w
d200: 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ith the filename
d210: 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  .** written into
d220: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
d230: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
d240: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63  alloc()].  The c
d250: 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20  aller should.** 
d260: 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
d270: 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72  free()] on the r
d280: 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61  esult to avoid a
d290: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a   memory leak..**
d2a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
d2b0: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
d2c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
d2d0: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
d2e0: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
d2f0: 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79  is used to query
d300: 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d   or set the.** m
d310: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
d320: 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c   bytes that will
d330: 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d   be used for mem
d340: 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a  ory-mapped I/O..
d350: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
d360: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
d370: 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20  a value of type 
d380: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68  sqlite3_int64 th
d390: 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69  at.** is an advi
d3a0: 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  sory maximum num
d3b0: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
d3c0: 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f  the file to memo
d3d0: 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20  ry map.  The.** 
d3e0: 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77  pointer is overw
d3f0: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
d400: 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20  old value.  The 
d410: 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61  limit is not cha
d420: 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76  nged if.** the v
d430: 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20  alue originally 
d440: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65  pointed to is ne
d450: 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74  gative, and so t
d460: 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74  he current limit
d470: 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72   .** can be quer
d480: 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69  ied by passing i
d490: 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  n a pointer to a
d4a0: 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
d4b0: 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d  .  This.** file-
d4c0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
d4d0: 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d  internally to im
d4e0: 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20  plement [PRAGMA 
d4f0: 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a  mmap_size]..**.*
d500: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
d510: 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20  CNTL_TRACE]].** 
d520: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d530: 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f  L_TRACE] file co
d540: 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61  ntrol provides a
d550: 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74  dvisory informat
d560: 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46  ion.** to the VF
d570: 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65  S about what the
d580: 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f   higher layers o
d590: 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61  f the SQLite sta
d5a0: 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a  ck are doing..**
d5b0: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   This file contr
d5c0: 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f  ol is used by so
d5d0: 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20  me VFS activity 
d5e0: 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e  tracing [shims].
d5f0: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
d600: 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   is a zero-termi
d610: 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48  nated string.  H
d620: 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20  igher layers in 
d630: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74  the.** SQLite st
d640: 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65  ack may generate
d650: 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68   instances of th
d660: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
d670: 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  if.** the [SQLIT
d680: 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43  E_USE_FCNTL_TRAC
d690: 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
d6a0: 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
d6b0: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  d..**.** <li>[[S
d6c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f  QLITE_FCNTL_HAS_
d6d0: 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b  MOVED]].** The [
d6e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53  SQLITE_FCNTL_HAS
d6f0: 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e  _MOVED] file con
d700: 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20  trol interprets 
d710: 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20  its argument as 
d720: 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
d730: 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 69  an integer and i
d740: 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f 6c 65  t writes a boole
d750: 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69 6e 74  an into that int
d760: 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a  eger depending.*
d770: 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20  * on whether or 
d780: 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68 61 73  not the file has
d790: 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d   been renamed, m
d7a0: 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74 65 64  oved, or deleted
d7b0: 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73   since it.** was
d7c0: 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a   first opened..*
d7d0: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
d7e0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
d7f0: 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68  T_HANDLE]].** Th
d800: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
d810: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
d820: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
d830: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
d840: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
d850: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
d860: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
d870: 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c 65 20  o swap the file 
d880: 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68 65 20  handle with the 
d890: 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  one.** pointed t
d8a0: 6f 20 62 79 20 74 68 65 20 70 41 72 67 20 61 72  o by the pArg ar
d8b0: 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20 63 61  gument.  This ca
d8c0: 70 61 62 69 6c 69 74 79 20 69 73 20 75 73 65 64  pability is used
d8d0: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 0a   during testing.
d8e0: 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ** and only need
d8f0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
d900: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
d910: 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ST is defined..*
d920: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
d930: 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43  E_FCNTL_WAL_BLOC
d940: 4b 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  K]].** The [SQLI
d950: 54 45 5f 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f  TE_FCNTL_WAL_BLO
d960: 43 4b 5d 20 69 73 20 61 20 73 69 67 6e 61 6c 20  CK] is a signal 
d970: 74 6f 20 74 68 65 20 56 46 53 20 6c 61 79 65 72  to the VFS layer
d980: 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 0a 2a   that it might.*
d990: 2a 20 62 65 20 61 64 76 61 6e 74 61 67 65 6f 75  * be advantageou
d9a0: 73 20 74 6f 20 62 6c 6f 63 6b 20 6f 6e 20 74 68  s to block on th
d9b0: 65 20 6e 65 78 74 20 57 41 4c 20 6c 6f 63 6b 20  e next WAL lock 
d9c0: 69 66 20 74 68 65 20 6c 6f 63 6b 20 69 73 20 6e  if the lock is n
d9d0: 6f 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a  ot immediately.*
d9e0: 2a 20 61 76 61 69 6c 61 62 6c 65 2e 20 20 54 68  * available.  Th
d9f0: 65 20 57 41 4c 20 73 75 62 73 79 73 74 65 6d 20  e WAL subsystem 
da00: 69 73 73 75 65 73 20 74 68 69 73 20 73 69 67 6e  issues this sign
da10: 61 6c 20 64 75 72 69 6e 67 20 72 61 72 65 0a 2a  al during rare.*
da20: 2a 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20  * circumstances 
da30: 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 78 20  in order to fix 
da40: 61 20 70 72 6f 62 6c 65 6d 20 77 69 74 68 20 70  a problem with p
da50: 72 69 6f 72 69 74 79 20 69 6e 76 65 72 73 69 6f  riority inversio
da60: 6e 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  n..** Applicatio
da70: 6e 73 20 73 68 6f 75 6c 64 20 3c 65 6d 3e 6e 6f  ns should <em>no
da80: 74 3c 2f 65 6d 3e 20 75 73 65 20 74 68 69 73 20  t</em> use this 
da90: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 2e 0a 2a 2a  file-control..**
daa0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
dab0: 5f 46 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 5d 0a  _FCNTL_ZIPVFS]].
dac0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
dad0: 43 4e 54 4c 5f 5a 49 50 56 46 53 5d 20 6f 70 63  CNTL_ZIPVFS] opc
dae0: 6f 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ode is implement
daf0: 65 64 20 62 79 20 7a 69 70 76 66 73 20 6f 6e 6c  ed by zipvfs onl
db00: 79 2e 20 41 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  y. All other.** 
db10: 56 46 53 20 73 68 6f 75 6c 64 20 72 65 74 75 72  VFS should retur
db20: 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e  n SQLITE_NOTFOUN
db30: 44 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  D for this opcod
db40: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  e..**.** <li>[[S
db50: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42 55 5d  QLITE_FCNTL_RBU]
db60: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
db70: 5f 46 43 4e 54 4c 5f 52 42 55 5d 20 6f 70 63 6f  _FCNTL_RBU] opco
db80: 64 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65  de is implemente
db90: 64 20 62 79 20 74 68 65 20 73 70 65 63 69 61 6c  d by the special
dba0: 20 56 46 53 20 75 73 65 64 20 62 79 0a 2a 2a 20   VFS used by.** 
dbb0: 74 68 65 20 52 42 55 20 65 78 74 65 6e 73 69 6f  the RBU extensio
dbc0: 6e 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20 6f 74 68  n only.  All oth
dbd0: 65 72 20 56 46 53 20 73 68 6f 75 6c 64 20 72 65  er VFS should re
dbe0: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4e 4f 54 46  turn SQLITE_NOTF
dbf0: 4f 55 4e 44 20 66 6f 72 0a 2a 2a 20 74 68 69 73  OUND for.** this
dc00: 20 6f 70 63 6f 64 65 2e 20 20 0a 2a 2a 20 3c 2f   opcode.  .** </
dc10: 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ul>.*/.#define S
dc20: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
dc30: 53 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20  STATE           
dc40: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
dc50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c  LITE_FCNTL_GET_L
dc60: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
dc70: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
dc80: 49 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f  ITE_FCNTL_SET_LO
dc90: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
dca0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
dcb0: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
dcc0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
dcd0: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
dce0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
dcf0: 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
dd00: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
dd10: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
dd20: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  E              6
dd30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
dd40: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
dd50: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a  ER            7.
dd60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
dd70: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
dd80: 44 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23  D            8.#
dd90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
dda0: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
ddb0: 52 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  RY          9.#d
ddc0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ddd0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20  TL_PERSIST_WAL  
dde0: 20 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65            10.#de
ddf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
de00: 4c 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20  L_OVERWRITE     
de10: 20 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66           11.#def
de20: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
de30: 5f 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20  _VFSNAME        
de40: 20 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69          12.#defi
de50: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
de60: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
de70: 49 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e  ITE    13.#defin
de80: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
de90: 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20  RAGMA           
dea0: 20 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65        14.#define
deb0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55   SQLITE_FCNTL_BU
dec0: 53 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20  SYHANDLER       
ded0: 20 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20       15.#define 
dee0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d  SQLITE_FCNTL_TEM
def0: 50 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20  PFILENAME       
df00: 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
df10: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50  QLITE_FCNTL_MMAP
df20: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
df30: 20 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51     18.#define SQ
df40: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45  LITE_FCNTL_TRACE
df50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
df60: 20 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c    19.#define SQL
df70: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
df80: 56 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20  VED             
df90: 20 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   20.#define SQLI
dfa0: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20  TE_FCNTL_SYNC   
dfb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
dfc0: 32 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  21.#define SQLIT
dfd0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
dfe0: 48 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32  HASETWO        2
dff0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
e000: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54  _FCNTL_WIN32_SET
e010: 5f 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33  _HANDLE       23
e020: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e030: 46 43 4e 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 20  FCNTL_WAL_BLOCK 
e040: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 0a               24.
e050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
e060: 43 4e 54 4c 5f 5a 49 50 56 46 53 20 20 20 20 20  CNTL_ZIPVFS     
e070: 20 20 20 20 20 20 20 20 20 20 20 20 32 35 0a 23              25.#
e080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
e090: 4e 54 4c 5f 52 42 55 20 20 20 20 20 20 20 20 20  NTL_RBU         
e0a0: 20 20 20 20 20 20 20 20 20 20 20 32 36 0a 0a 2f             26../
e0b0: 2a 20 64 65 70 72 65 63 61 74 65 64 20 6e 61 6d  * deprecated nam
e0c0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
e0d0: 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_GET_LOCKPRO
e0e0: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
e0f0: 54 45 5f 46 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43  TE_FCNTL_GET_LOC
e100: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
e110: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
e120: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
e130: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 45   SQLITE_FCNTL_SE
e140: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 0a  T_LOCKPROXYFILE.
e150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
e160: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
e170: 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43 4e        SQLITE_FCN
e180: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 0a 0a 0a  TL_LAST_ERRNO...
e190: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e1a0: 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a  Mutex Handle.**.
e1b0: 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64  ** The mutex mod
e1c0: 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74  ule within SQLit
e1d0: 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74  e defines [sqlit
e1e0: 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20  e3_mutex] to be 
e1f0: 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74  an.** abstract t
e200: 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20  ype for a mutex 
e210: 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c  object.  The SQL
e220: 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c  ite core never l
e230: 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69  ooks.** at the i
e240: 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
e250: 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71  tation of an [sq
e260: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49  lite3_mutex].  I
e270: 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20  t only.** deals 
e280: 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f  with pointers to
e290: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
e2a0: 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  tex] object..**.
e2b0: 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63  ** Mutexes are c
e2c0: 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  reated using [sq
e2d0: 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f  lite3_mutex_allo
e2e0: 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  c()]..*/.typedef
e2f0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
e300: 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75  mutex sqlite3_mu
e310: 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tex;../*.** CAPI
e320: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
e330: 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ce Object.**.** 
e340: 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
e350: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
e360: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
e370: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
e380: 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74  een.** the SQLit
e390: 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75  e core and the u
e3a0: 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74  nderlying operat
e3b0: 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65  ing system.  The
e3c0: 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65   "vfs".** in the
e3d0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a   name of the obj
e3e0: 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22  ect stands for "
e3f0: 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73  virtual file sys
e400: 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68  tem".  See.** th
e410: 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63  e [VFS | VFS doc
e420: 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
e430: 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74  further informat
e440: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76  ion..**.** The v
e450: 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72  alue of the iVer
e460: 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e  sion field is in
e470: 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61  itially 1 but ma
e480: 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a  y be larger in.*
e490: 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e  * future version
e4a0: 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64  s of SQLite.  Ad
e4b0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
e4c0: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
e4d0: 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63  to this.** objec
e4e0: 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73  t when the iVers
e4f0: 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63  ion value is inc
e500: 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68  reased.  Note th
e510: 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65  at the structure
e520: 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74  .** of the sqlit
e530: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68  e3_vfs object ch
e540: 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61  anges in the tra
e550: 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  nsaction between
e560: 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
e570: 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36  on 3.5.9 and 3.6
e580: 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69  .0 and yet the i
e590: 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61  Version field wa
e5a0: 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65  s not.** modifie
e5b0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f  d..**.** The szO
e5c0: 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74  sFile field is t
e5d0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  he size of the s
e5e0: 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74  ubclassed [sqlit
e5f0: 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75  e3_file].** stru
e600: 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68  cture used by th
e610: 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e  is VFS.  mxPathn
e620: 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d  ame is the maxim
e630: 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20  um length of.** 
e640: 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68  a pathname in th
e650: 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65  is VFS..**.** Re
e660: 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33  gistered sqlite3
e670: 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65  _vfs objects are
e680: 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65   kept on a linke
e690: 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79  d list formed by
e6a0: 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f  .** the pNext po
e6b0: 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c  inter.  The [sql
e6c0: 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65  ite3_vfs_registe
e6d0: 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  r()].** and [sql
e6e0: 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73  ite3_vfs_unregis
e6f0: 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ter()] interface
e700: 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69  s manage this li
e710: 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61  st.** in a threa
e720: 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65  d-safe way.  The
e730: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69   [sqlite3_vfs_fi
e740: 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a  nd()] interface.
e750: 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20  ** searches the 
e760: 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74  list.  Neither t
e770: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  he application c
e780: 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a  ode nor the VFS.
e790: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
e7a0: 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  n should use the
e7b0: 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a   pNext pointer..
e7c0: 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20  **.** The pNext 
e7d0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c  field is the onl
e7e0: 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73  y field in the s
e7f0: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74  qlite3_vfs.** st
e800: 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c  ructure that SQL
e810: 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f  ite will ever mo
e820: 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69  dify.  SQLite wi
e830: 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a  ll only access.*
e840: 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  * or modify this
e850: 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c   field while hol
e860: 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61  ding a particula
e870: 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a  r static mutex..
e880: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
e890: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
e8a0: 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20  modify anything 
e8b0: 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74  within the sqlit
e8c0: 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74  e3_vfs.** object
e8d0: 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74   once the object
e8e0: 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74   has been regist
e8f0: 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ered..**.** The 
e900: 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64  zName field hold
e910: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
e920: 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54  e VFS module.  T
e930: 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20  he name must.** 
e940: 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73  be unique across
e950: 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73   all VFS modules
e960: 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
e970: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a  3_vfs.xOpen]].**
e980: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
e990: 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69  ees that the zFi
e9a0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
e9b0: 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20   to xOpen.** is 
e9c0: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f  either a NULL po
e9d0: 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20  inter or string 
e9e0: 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
e9f0: 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29   xFullPathname()
ea00: 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61   with an optiona
ea10: 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a  l suffix added..
ea20: 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20  ** ^If a suffix 
ea30: 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20  is added to the 
ea40: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
ea50: 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20  ter, it will.** 
ea60: 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e  consist of a sin
ea70: 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65  gle "-" characte
ea80: 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f  r followed by no
ea90: 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31   more than.** 11
eaa0: 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e   alphanumeric an
eab0: 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74  d/or "-" charact
eac0: 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ers..** ^SQLite 
ead0: 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65  further guarante
eae0: 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73  es that.** the s
eaf0: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61  tring will be va
eb00: 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65  lid and unchange
eb10: 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29  d until xClose()
eb20: 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42   is.** called. B
eb30: 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72  ecause of the pr
eb40: 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c  evious sentence,
eb50: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
eb60: 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c  _file] can safel
eb70: 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65  y store a pointe
eb80: 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65  r to the.** file
eb90: 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73  name if it needs
eba0: 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65   to remember the
ebb0: 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f   filename for so
ebc0: 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66  me reason..** If
ebd0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
ebe0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
ebf0: 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  n is a NULL poin
ec00: 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a  ter then xOpen.*
ec10: 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74  * must invent it
ec20: 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20  s own temporary 
ec30: 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c  name for the fil
ec40: 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68  e.  ^Whenever th
ec50: 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20  e .** xFilename 
ec60: 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c  parameter is NUL
ec70: 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62  L it will also b
ec80: 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20  e the case that 
ec90: 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72  the.** flags par
eca0: 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c  ameter will incl
ecb0: 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ude [SQLITE_OPEN
ecc0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e  _DELETEONCLOSE].
ecd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73  .**.** The flags
ece0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
ecf0: 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c  en() includes al
ed00: 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a  l bits set in.**
ed10: 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
ed20: 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ent to [sqlite3_
ed30: 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20  open_v2()].  Or 
ed40: 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  if [sqlite3_open
ed50: 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
ed60: 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20  e3_open16()] is 
ed70: 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73  used, then flags
ed80: 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61   includes at lea
ed90: 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  st.** [SQLITE_OP
eda0: 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
edb0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
edc0: 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70  ATE]. .** If xOp
edd0: 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c  en() opens a fil
ede0: 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e  e read-only then
edf0: 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c   it sets *pOutFl
ee00: 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64  ags to.** includ
ee10: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
ee20: 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72  EADONLY].  Other
ee30: 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c   bits in *pOutFl
ee40: 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a  ags may be set..
ee50: 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77  **.** ^(SQLite w
ee60: 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ill also add one
ee70: 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
ee80: 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
ee90: 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20  Open().** call, 
eea0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
eeb0: 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70   object being op
eec0: 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ened:.**.** <ul>
eed0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
eee0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a  E_OPEN_MAIN_DB].
eef0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ef00: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
ef10: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
ef20: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
ef30: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
ef40: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
ef50: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
ef60: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41  [SQLITE_OPEN_TRA
ef70: 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c  NSIENT_DB].** <l
ef80: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ef90: 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  _SUBJOURNAL].** 
efa0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
efb0: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
efc0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
efd0: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a  ITE_OPEN_WAL].**
efe0: 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
eff0: 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c  he file I/O impl
f000: 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75  ementation can u
f010: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79  se the object ty
f020: 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63  pe flags to.** c
f030: 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74  hange the way it
f040: 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65   deals with file
f050: 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  s.  For example,
f060: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a   an application.
f070: 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  ** that does not
f080: 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73   care about cras
f090: 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f  h recovery or ro
f0a0: 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b  llback might mak
f0b0: 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66  e.** the open of
f0c0: 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20   a journal file 
f0d0: 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73  a no-op.  Writes
f0e0: 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c   to this journal
f0f0: 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62   would.** also b
f100: 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e  e no-ops, and an
f110: 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61  y attempt to rea
f120: 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f  d the journal wo
f130: 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51  uld return.** SQ
f140: 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20  LITE_IOERR.  Or 
f150: 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
f160: 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69  on might recogni
f170: 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61  ze that a databa
f180: 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20  se.** file will 
f190: 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c  be doing page-al
f1a0: 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61  igned sector rea
f1b0: 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e  ds and writes in
f1c0: 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64   a random.** ord
f1d0: 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74  er and set up it
f1e0: 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20  s I/O subsystem 
f1f0: 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a  accordingly..**.
f200: 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  ** SQLite might 
f210: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
f220: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
f230: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
f240: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
f250: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ul>.** <li> [SQL
f260: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
f270: 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20  NCLOSE].** <li> 
f280: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
f290: 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e  LUSIVE].** </ul>
f2a0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
f2b0: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
f2c0: 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e  CLOSE] flag mean
f2d0: 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  s the file shoul
f2e0: 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20  d be.** deleted 
f2f0: 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65  when it is close
f300: 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  d.  ^The [SQLITE
f310: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
f320: 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  OSE].** will be 
f330: 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74  set for TEMP dat
f340: 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72  abases and their
f350: 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73   journals, trans
f360: 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65  ient.** database
f370: 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61  s, and subjourna
f380: 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  ls..**.** ^The [
f390: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
f3a0: 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61  USIVE] flag is a
f3b0: 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f  lways used in co
f3c0: 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74  njunction.** wit
f3d0: 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  h the [SQLITE_OP
f3e0: 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c  EN_CREATE] flag,
f3f0: 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20   which are both 
f400: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c  directly.** anal
f410: 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45  ogous to the O_E
f420: 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20  XCL and O_CREAT 
f430: 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53  flags of the POS
f440: 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49  IX open().** API
f450: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50  .  The SQLITE_OP
f460: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61  EN_EXCLUSIVE fla
f470: 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77  g, when paired w
f480: 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49  ith the .** SQLI
f490: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20  TE_OPEN_CREATE, 
f4a0: 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  is used to indic
f4b0: 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68  ate that file sh
f4c0: 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62  ould always.** b
f4d0: 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74  e created, and t
f4e0: 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72  hat it is an err
f4f0: 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79  or if it already
f500: 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69   exists..** It i
f510: 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65  s <i>not</i> use
f520: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
f530: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
f540: 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20   opened .** for 
f550: 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73  exclusive access
f560: 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73  ..**.** ^At leas
f570: 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73  t szOsFile bytes
f580: 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61   of memory are a
f590: 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
f5a0: 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68  te.** to hold th
f5b0: 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  e  [sqlite3_file
f5c0: 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73  ] structure pass
f5d0: 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a  ed as the third.
f5e0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78  ** argument to x
f5f0: 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e  Open.  The xOpen
f600: 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74   method does not
f610: 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f   have to.** allo
f620: 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75  cate the structu
f630: 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75  re; it should ju
f640: 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20  st fill it in.  
f650: 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  Note that.** the
f660: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75   xOpen method mu
f670: 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74  st set the sqlit
f680: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
f690: 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20   to either.** a 
f6a0: 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69  valid [sqlite3_i
f6b0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
f6c0: 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78  t or to NULL.  x
f6d0: 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20  Open must do.** 
f6e0: 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65  this even if the
f6f0: 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51   open fails.  SQ
f700: 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61  Lite expects tha
f710: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
f720: 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65  le.pMethods.** e
f730: 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76  lement will be v
f740: 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e  alid after xOpen
f750: 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c   returns regardl
f760: 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65  ess of the succe
f770: 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65  ss.** or failure
f780: 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61   of the xOpen ca
f790: 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69  ll..**.** [[sqli
f7a0: 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d  te3_vfs.xAccess]
f7b0: 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20  ].** ^The flags 
f7c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63  argument to xAcc
f7d0: 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51  ess() may be [SQ
f7e0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
f7f0: 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66  TS].** to test f
f800: 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65  or the existence
f810: 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b   of a file, or [
f820: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
f830: 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74  ADWRITE] to.** t
f840: 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
f850: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61  le is readable a
f860: 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20  nd writable, or 
f870: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
f880: 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  EAD].** to test 
f890: 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69  whether a file i
f8a0: 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61  s at least reada
f8b0: 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20  ble.   The file 
f8c0: 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65  can be a.** dire
f8d0: 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  ctory..**.** ^SQ
f8e0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73  Lite will always
f8f0: 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61   allocate at lea
f900: 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20  st mxPathname+1 
f910: 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a  bytes for the.**
f920: 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78   output buffer x
f930: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54  FullPathname.  T
f940: 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66  he exact size of
f950: 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
f960: 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61  er.** is also pa
f970: 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65  ssed as a parame
f980: 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74  ter to both  met
f990: 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74  hods. If the out
f9a0: 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
f9b0: 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67   not large enoug
f9c0: 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  h, [SQLITE_CANTO
f9d0: 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72  PEN] should be r
f9e0: 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74  eturned. Since t
f9f0: 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65  his is.** handle
fa00: 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72  d as a fatal err
fa10: 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66  or by SQLite, vf
fa20: 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
fa30: 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f  s should endeavo
fa40: 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20  r.** to prevent 
fa50: 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20  this by setting 
fa60: 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20  mxPathname to a 
fa70: 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72  sufficiently lar
fa80: 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  ge value..**.** 
fa90: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
faa0: 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75  ), xSleep(), xCu
fab0: 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64  rrentTime(), and
fac0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
fad0: 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  64().** interfac
fae0: 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63  es are not stric
faf0: 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68  tly a part of th
fb00: 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75  e filesystem, bu
fb10: 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e  t they are.** in
fb20: 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46  cluded in the VF
fb30: 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20  S structure for 
fb40: 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a  completeness..**
fb50: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
fb60: 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65  () function atte
fb70: 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e  mpts to return n
fb80: 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f  Bytes bytes.** o
fb90: 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72  f good-quality r
fba0: 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a  andomness into z
fbb0: 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e  Out.  The return
fbc0: 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65   value is.** the
fbd0: 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f   actual number o
fbe0: 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  f bytes of rando
fbf0: 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a  mness obtained..
fc00: 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20  ** The xSleep() 
fc10: 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68  method causes th
fc20: 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64  e calling thread
fc30: 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74   to sleep for at
fc40: 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75  .** least the nu
fc50: 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63  mber of microsec
fc60: 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68  onds given.  ^Th
fc70: 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29  e xCurrentTime()
fc80: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
fc90: 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20  ns a Julian Day 
fca0: 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63  Number for the c
fcb0: 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20  urrent date and 
fcc0: 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f  time as.** a flo
fcd0: 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
fce0: 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72  e..** ^The xCurr
fcf0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
fd00: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61  ethod returns, a
fd10: 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  s an integer, th
fd20: 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20  e Julian.** Day 
fd30: 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65  Number multiplie
fd40: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
fd50: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
fd60: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
fd70: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
fd80: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
fd90: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
fda0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
fdb0: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
fdc0: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
fdd0: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
fde0: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
fdf0: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
fe00: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
fe10: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
fe20: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
fe30: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
fe40: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
fe50: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
fe60: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
fe70: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
fe80: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
fe90: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
fea0: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
feb0: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
fec0: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
fed0: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
fee0: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
fef0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
ff00: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
ff10: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
ff20: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
ff30: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
ff40: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
ff50: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
ff60: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
ff70: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
ff80: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
ff90: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
ffa0: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
ffb0: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
ffc0: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
ffd0: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
ffe0: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
fff0: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
10000 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
10010 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
10020 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
10030 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
10040 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
10050 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
10060 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
10070 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
10080 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
10090 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
100a0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
100b0 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
100c0 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
100d0 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
100e0 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
100f0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
10100 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
10110 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
10120 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
10130 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
10140 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
10150 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
10160 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
10170 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
10180 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
10190 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
101a0 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
101b0 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
101c0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
101d0 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
101e0 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
101f0 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
10200 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
10210 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
10220 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
10230 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
10240 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
10250 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
10260 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
10270 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
10280 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
10290 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
102a0 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
102b0 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
102c0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
102d0 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
102e0 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
102f0 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
10300 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
10310 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
10320 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
10330 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
10340 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
10350 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
10360 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
10370 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
10380 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
10390 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
103a0 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
103b0 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
103c0 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
103d0 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
103e0 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
103f0 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
10400 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
10410 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
10420 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
10430 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
10440 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
10450 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
10460 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
10470 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
10480 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
10490 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
104a0 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
104b0 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
104c0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
104d0 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
104e0 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
104f0 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
10500 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10510 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
10520 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
10530 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
10540 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
10550 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
10560 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
10570 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
10580 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
10590 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
105a0 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
105b0 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
105c0 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
105d0 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
105e0 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
105f0 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
10600 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
10610 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
10620 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
10630 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
10640 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
10650 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
10660 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
10670 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
10680 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
10690 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
106a0 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
106b0 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
106c0 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
106d0 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
106e0 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
106f0 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
10700 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
10710 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
10720 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
10730 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
10740 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
10750 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
10760 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
10770 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
10780 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
10790 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
107a0 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
107b0 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
107c0 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
107d0 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
107e0 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
107f0 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
10800 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
10810 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
10820 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
10830 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
10840 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
10850 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
10860 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
10870 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
10880 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
10890 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
108a0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
108b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
108c0 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
108d0 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
108e0 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
108f0 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
10900 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
10910 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
10920 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
10930 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20  ended in figure 
10940 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
10950 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
10960 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
10970 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
10980 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
10990 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
109a0 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
109b0 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
109c0 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
109d0 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
109e0 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
109f0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
10a00 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
10a10 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
10a20 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
10a30 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
10a40 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
10a50 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
10a60 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
10a70 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
10a80 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
10a90 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
10aa0 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
10ab0 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
10ac0 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
10ad0 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
10ae0 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
10af0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
10b00 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
10b10 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
10b20 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
10b30 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
10b40 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
10b50 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
10b60 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
10b70 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
10b80 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
10b90 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
10ba0 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
10bb0 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
10bc0 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
10bd0 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
10be0 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
10bf0 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
10c00 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
10c10 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
10c20 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
10c30 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
10c40 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
10c50 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
10c60 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
10c70 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
10c80 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
10c90 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
10ca0 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
10cb0 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
10cc0 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
10cd0 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
10ce0 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
10cf0 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
10d00 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
10d10 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
10d20 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
10d30 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
10d40 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
10d50 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
10d60 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
10d70 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
10d80 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
10d90 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
10da0 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10db0 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
10dc0 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
10dd0 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
10de0 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
10df0 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
10e00 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
10e10 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
10e20 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
10e30 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
10e40 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
10e50 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
10e60 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
10e70 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
10e80 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
10e90 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
10ea0 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
10eb0 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
10ec0 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
10ed0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
10ee0 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
10ef0 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
10f00 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
10f10 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
10f20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
10f30 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
10f40 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
10f50 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
10f60 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
10f70 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
10f80 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
10f90 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
10fa0 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
10fb0 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
10fc0 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
10fd0 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
10fe0 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
10ff0 77 61 73 20 67 69 76 65 6e 20 6f 6e 20 74 68 65  was given on the
11000 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
11010 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
11020 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
11030 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
11040 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
11050 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
11060 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
11070 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
11080 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
11090 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
110a0 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
110b0 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
110c0 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
110d0 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
110e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
110f0 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
11100 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
11110 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
11120 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
11130 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
11140 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
11150 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
11160 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
11170 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
11180 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
11190 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
111a0 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
111b0 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
111c0 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
111d0 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
111e0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
111f0 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
11200 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
11210 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
11220 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
11230 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
11240 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
11250 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
11260 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
11270 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
11280 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
11290 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
112a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
112b0 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
112c0 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
112d0 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
112e0 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
112f0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
11300 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
11310 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
11320 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
11330 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
11340 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
11350 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
11360 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
11370 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
11380 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
11390 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
113a0 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
113b0 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
113c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
113d0 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
113e0 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
113f0 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
11400 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
11410 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
11420 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
11430 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
11440 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
11450 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
11460 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
11470 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11480 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
11490 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
114a0 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
114b0 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
114c0 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
114d0 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
114e0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
114f0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
11500 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
11510 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
11520 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
11530 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
11540 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11550 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
11560 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
11570 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
11580 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
11590 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
115a0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
115b0 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
115c0 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
115d0 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
115e0 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
115f0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
11600 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
11610 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11620 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
11630 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
11640 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
11650 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
11660 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
11670 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
11680 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
11690 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
116a0 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
116b0 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
116c0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
116d0 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
116e0 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
116f0 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
11700 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
11710 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
11720 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
11730 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
11740 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
11750 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
11760 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
11770 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11780 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
11790 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
117a0 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
117b0 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
117c0 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
117d0 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
117e0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
117f0 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
11800 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
11810 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11820 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
11830 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
11840 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
11850 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11860 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
11870 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
11880 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
11890 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
118a0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
118b0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
118c0 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
118d0 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
118e0 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
118f0 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
11900 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
11910 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
11920 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
11930 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
11940 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
11950 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
11960 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
11970 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
11980 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
11990 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
119a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
119b0 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
119c0 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
119d0 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
119e0 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
119f0 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
11a00 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
11a10 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
11a20 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
11a30 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
11a40 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
11a50 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
11a60 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
11a70 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
11a80 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11a90 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
11aa0 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
11ab0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
11ac0 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
11ad0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
11ae0 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
11af0 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
11b00 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
11b10 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
11b20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
11b30 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
11b40 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
11b50 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
11b60 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
11b70 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
11b80 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
11b90 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
11ba0 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
11bb0 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
11bc0 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
11bd0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
11be0 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
11bf0 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
11c00 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
11c10 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
11c20 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
11c30 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
11c40 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
11c50 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
11c60 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
11c70 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
11c80 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
11c90 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
11ca0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
11cb0 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
11cc0 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
11cd0 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
11ce0 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
11cf0 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
11d00 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
11d10 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
11d20 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
11d30 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
11d40 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
11d50 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
11d60 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
11d70 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
11d80 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
11d90 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
11da0 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
11db0 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
11dc0 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
11dd0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
11de0 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
11df0 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
11e00 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
11e10 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
11e20 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
11e30 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
11e40 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
11e50 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
11e60 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
11e70 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
11e80 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
11e90 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
11ea0 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
11eb0 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
11ec0 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
11ed0 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
11ee0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
11ef0 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
11f00 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
11f10 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
11f20 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
11f30 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
11f40 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
11f50 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
11f60 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
11f70 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
11f80 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
11f90 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
11fa0 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
11fb0 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
11fc0 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
11fd0 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
11fe0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11ff0 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
12000 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
12010 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
12020 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
12030 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
12040 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
12050 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
12060 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
12070 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
12080 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
12090 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
120a0 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
120b0 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
120c0 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
120d0 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
120e0 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
120f0 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
12100 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
12110 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
12120 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
12130 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
12140 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
12150 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
12160 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
12170 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
12180 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
12190 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
121a0 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
121b0 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
121c0 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
121d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
121e0 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
121f0 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
12200 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
12210 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
12220 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
12230 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
12240 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
12250 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
12260 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
12270 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
12280 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
12290 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
122a0 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
122b0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
122c0 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ze(void);.SQLITE
122d0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
122e0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
122f0 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a  shutdown(void);.
12300 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
12310 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
12320 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f  lite3_os_init(vo
12330 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  id);.SQLITE_API 
12340 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
12350 4c 4c 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  LL sqlite3_os_en
12360 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d(void);../*.** 
12370 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67  CAPI3REF: Config
12380 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65  uring The SQLite
12390 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54   Library.**.** T
123a0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  he sqlite3_confi
123b0 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
123c0 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c   used to make gl
123d0 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69  obal configurati
123e0 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
123f0 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
12400 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20   to tune SQLite 
12410 74 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20  to the specific 
12420 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20  needs of.** the 
12430 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68  application.  Th
12440 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  e default config
12450 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d  uration is recom
12460 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a  mended for most.
12470 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
12480 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74  and so this rout
12490 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e  ine is usually n
124a0 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49  ot necessary.  I
124b0 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64  t is.** provided
124c0 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65   to support rare
124d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
124e0 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73  th unusual needs
124f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
12500 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
12510 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68  erface is not th
12520 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61  readsafe.  The a
12530 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75  pplication.** mu
12540 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e  st insure that n
12550 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
12560 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e  nterfaces are in
12570 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a  voked by other.*
12580 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20  * threads while 
12590 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
125a0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75   is running.  Fu
125b0 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74  rthermore, sqlit
125c0 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d  e3_config().** m
125d0 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b  ay only be invok
125e0 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72  ed prior to libr
125f0 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ary initializati
12600 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
12610 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12620 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74  )] or after shut
12630 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33  down by [sqlite3
12640 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a  _shutdown()]..**
12650 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e   ^If sqlite3_con
12660 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20  fig() is called 
12670 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69  after [sqlite3_i
12680 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64  nitialize()] and
12690 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69   before.** [sqli
126a0 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
126b0 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74  then it will ret
126c0 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  urn SQLITE_MISUS
126d0 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65  E..** Note, howe
126e0 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74  ver, that ^sqlit
126f0 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20  e3_config() can 
12700 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72  be called as par
12710 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  t of the.** impl
12720 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  ementation of an
12730 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
12740 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73  ined [sqlite3_os
12750 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _init()]..**.** 
12760 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
12770 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
12780 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74  nfig() is an int
12790 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75  eger.** [configu
127a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74  ration option] t
127b0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a  hat determines.*
127c0 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20  * what property 
127d0 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20  of SQLite is to 
127e0 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20  be configured.  
127f0 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d  Subsequent argum
12800 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70  ents.** vary dep
12810 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63  ending on the [c
12820 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
12830 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66  ion].** in the f
12840 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
12850 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e  *.** ^When a con
12860 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12870 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65  n is set, sqlite
12880 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  3_config() retur
12890 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
128a0 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f  ** ^If the optio
128b0 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20  n is unknown or 
128c0 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
128d0 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69   to set the opti
128e0 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20  on.** then this 
128f0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
12900 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  a non-zero [erro
12910 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49  r code]..*/.SQLI
12920 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
12930 45 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f  E_CDECL sqlite3_
12940 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29  config(int, ...)
12950 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
12960 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74  F: Configure dat
12970 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
12980 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  s.** METHOD: sql
12990 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ite3.**.** The s
129a0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
129b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
129c0 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e  used to make con
129d0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
129e0 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61  anges to a [data
129f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
12a00 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
12a10 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a   is similar to.*
12a20 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
12a30 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74  g()] except that
12a40 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70   the changes app
12a50 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a  ly to a single.*
12a60 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
12a70 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69  ection] (specifi
12a80 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
12a90 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a  argument)..**.**
12aa0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
12ab0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
12ac0 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e  db_config(D,V,..
12ad0 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53  .)  is the.** [S
12ae0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
12af0 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69  OOKASIDE | confi
12b00 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d  guration verb] -
12b10 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65   an integer code
12b20 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61   .** that indica
12b30 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20  tes what aspect 
12b40 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  of the [database
12b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
12b60 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64  being configured
12b70 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20  ..** Subsequent 
12b80 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64  arguments vary d
12b90 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
12ba0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
12bb0 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73  rb..**.** ^Calls
12bc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
12bd0 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53  onfig() return S
12be0 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20  QLITE_OK if and 
12bf0 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63  only if.** the c
12c00 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65  all is considere
12c10 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f  d successful..*/
12c20 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
12c30 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73 71 6c  SQLITE_CDECL sql
12c40 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73  ite3_db_config(s
12c50 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c  qlite3*, int op,
12c60 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
12c70 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
12c80 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e  llocation Routin
12c90 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  es.**.** An inst
12ca0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
12cb0 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
12cc0 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
12cd0 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  n SQLite.** and 
12ce0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
12cf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12d00 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  ines..**.** This
12d10 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20   object is used 
12d20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63  in only one plac
12d30 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20  e in the SQLite 
12d40 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20  interface..** A 
12d50 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
12d60 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
12d70 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67  bject is the arg
12d80 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c  ument to.** [sql
12d90 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
12da0 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72  hen the configur
12db0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a  ation option is.
12dc0 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
12dd0 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51  G_MALLOC] or [SQ
12de0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
12df0 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20  ALLOC].  .** By 
12e00 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74  creating an inst
12e10 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
12e20 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69  ect.** and passi
12e30 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
12e40 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
12e50 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
12e60 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66  ).** during conf
12e70 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70  iguration, an ap
12e80 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70  plication can sp
12e90 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61  ecify an alterna
12ea0 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  tive.** memory a
12eb0 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73  llocation subsys
12ec0 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74  tem for SQLite t
12ed0 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66  o use for all of
12ee0 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20   its.** dynamic 
12ef0 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a  memory needs..**
12f00 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51  .** Note that SQ
12f10 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20  Lite comes with 
12f20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69  several [built-i
12f30 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
12f40 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65  ors].** that are
12f50 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75   perfectly adequ
12f60 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72  ate for the over
12f70 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74  whelming majorit
12f80 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
12f90 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68  s.** and that th
12fa0 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c  is object is onl
12fb0 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69  y useful to a ti
12fc0 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61  ny minority of a
12fd0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77  pplications.** w
12fe0 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ith specialized 
12ff0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13000 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20  n requirements. 
13010 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a   This object is.
13020 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72  ** also used dur
13030 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53  ing testing of S
13040 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
13050 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74  o specify an alt
13060 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f  ernative.** memo
13070 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61  ry allocator tha
13080 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f  t simulates memo
13090 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79  ry out-of-memory
130a0 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a   conditions in.*
130b0 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66  * order to verif
130c0 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65  y that SQLite re
130d0 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c  covers gracefull
130e0 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63  y from such.** c
130f0 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  onditions..**.**
13100 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52   The xMalloc, xR
13110 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65  ealloc, and xFre
13120 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77  e methods must w
13130 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20  ork like the.** 
13140 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f  malloc(), reallo
13150 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66  c() and free() f
13160 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68  unctions from th
13170 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
13180 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  rary..** ^SQLite
13190 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
131a0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
131b0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c  ment to.** xReal
131c0 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20  loc is always a 
131d0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
131e0 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74  y a prior call t
131f0 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a  o xRoundup..**.*
13200 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72  * xSize should r
13210 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61  eturn the alloca
13220 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65  ted size of a me
13230 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
13240 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62  ** previously ob
13250 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c  tained from xMal
13260 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e  loc or xRealloc.
13270 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20    The allocated 
13280 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79  size.** is alway
13290 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69  s at least as bi
132a0 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74  g as the request
132b0 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20  ed size but may 
132c0 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a  be larger..**.**
132d0 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65   The xRoundup me
132e0 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61  thod returns wha
132f0 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61  t would be the a
13300 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
13310 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  .** a memory all
13320 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20  ocation given a 
13330 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65  particular reque
13340 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74  sted size.  Most
13350 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
13360 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d  ators round up m
13370 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13380 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68  s at least to th
13390 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a  e next multiple.
133a0 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61  ** of 8.  Some a
133b0 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20  llocators round 
133c0 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d  up to a larger m
133d0 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20  ultiple or to a 
133e0 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45  power of 2..** E
133f0 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  very memory allo
13400 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63  cation request c
13410 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68  oming in through
13420 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
13430 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  ()].** or [sqlit
13440 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69  e3_realloc()] fi
13450 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64  rst calls xRound
13460 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70  up.  If xRoundup
13470 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20   returns 0, .** 
13480 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20  that causes the 
13490 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65  corresponding me
134a0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
134b0 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54  to fail..**.** T
134c0 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
134d0 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20  initializes the 
134e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
134f0 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  .  For example,.
13500 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
13510 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
13520 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
13530 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
13540 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
13550 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
13560 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
13570 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
13580 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
13590 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
135a0 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
135b0 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
135c0 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
135d0 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
135e0 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
135f0 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
13600 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
13610 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
13620 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
13630 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
13640 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
13650 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
13660 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
13670 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
13680 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
13690 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
136a0 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
136b0 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
136c0 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
136d0 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
136e0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
136f0 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
13700 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
13710 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
13720 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
13730 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
13740 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
13750 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
13760 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
13770 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
13780 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13790 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
137a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
137b0 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
137c0 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
137d0 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
137e0 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
137f0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
13800 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
13810 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
13820 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
13830 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
13840 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
13850 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
13860 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
13870 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
13880 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
13890 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
138a0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
138b0 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
138c0 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
138d0 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
138e0 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
138f0 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
13900 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
13910 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
13920 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13930 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
13940 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
13950 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
13960 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
13970 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
13980 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
13990 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
139a0 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
139b0 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
139c0 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
139d0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
139e0 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
139f0 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
13a00 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
13a10 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
13a20 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
13a30 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
13a40 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
13a50 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
13a60 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
13a70 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
13a80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
13a90 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
13aa0 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
13ab0 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
13ac0 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
13ad0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
13ae0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
13af0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
13b00 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
13b10 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
13b20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
13b30 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
13b40 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
13b50 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
13b60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
13b70 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
13b80 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
13b90 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
13ba0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
13bb0 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
13bc0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
13bd0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13be0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
13bf0 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
13c00 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
13c10 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
13c20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
13c30 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
13c40 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
13c50 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
13c60 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
13c70 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
13c80 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
13c90 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
13ca0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
13cb0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
13cc0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
13cd0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13ce0 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
13cf0 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
13d00 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
13d10 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
13d20 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
13d30 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
13d40 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
13d50 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
13d60 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
13d70 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13d80 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
13d90 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
13da0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
13db0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
13dc0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
13dd0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
13de0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
13df0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
13e00 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
13e10 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
13e20 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
13e30 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
13e40 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
13e50 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
13e60 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
13e70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
13e80 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
13e90 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
13ea0 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
13eb0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
13ec0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
13ed0 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
13ee0 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
13ef0 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
13f00 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
13f10 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
13f20 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
13f30 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
13f40 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
13f50 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
13f60 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
13f70 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
13f80 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
13f90 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
13fa0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
13fb0 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
13fc0 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
13fd0 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
13fe0 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
13ff0 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
14000 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
14010 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
14020 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
14030 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
14040 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14050 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
14060 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14070 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
14080 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14090 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
140a0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
140b0 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
140c0 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
140d0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
140e0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
140f0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
14100 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
14110 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
14120 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
14130 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
14140 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
14150 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
14160 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
14170 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
14180 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
14190 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
141a0 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
141b0 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
141c0 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
141d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
141e0 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
141f0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
14200 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
14210 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
14220 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
14230 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
14240 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
14250 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
14260 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
14270 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
14280 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
14290 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
142a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
142b0 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
142c0 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
142d0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
142e0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
142f0 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
14300 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
14310 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
14320 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
14330 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
14340 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
14350 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
14360 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
14370 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
14380 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
14390 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
143a0 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
143b0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
143c0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
143d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
143e0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
143f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14400 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
14410 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14420 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
14430 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
14440 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
14450 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
14460 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
14470 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
14480 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
14490 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
144a0 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
144b0 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
144c0 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
144d0 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
144e0 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
144f0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14500 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
14510 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
14520 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
14530 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
14540 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
14550 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
14560 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
14570 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14580 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
14590 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
145a0 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
145b0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
145c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
145d0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
145e0 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
145f0 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
14600 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
14610 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
14620 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14630 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
14640 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
14650 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
14660 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
14670 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
14680 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
14690 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
146a0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
146b0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
146c0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
146d0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
146e0 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
146f0 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
14700 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
14710 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
14720 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
14730 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14740 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
14750 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
14760 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
14770 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
14780 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
14790 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
147a0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
147b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
147c0 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
147d0 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
147e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
147f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
14800 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61 6b  ALLOC option tak
14810 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
14820 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a 2a  ment which is .*
14830 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  * a pointer to a
14840 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
14850 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
14860 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
14870 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  e..** The argume
14880 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
14890 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
148a0 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
148b0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
148c0 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
148d0 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
148e0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
148f0 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
14900 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
14910 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
14920 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
14930 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
14940 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
14950 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
14960 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
14970 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
14980 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
14990 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
149a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
149b0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
149c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
149d0 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
149e0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65 20  >.** <dd> ^(The 
149f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14a00 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74  TMALLOC option t
14a10 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
14a20 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a 20  gument which.** 
14a30 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14a40 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
14a50 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
14a60 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
14a70 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  re..** The [sqli
14a80 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
14a90 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
14aa0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
14ab0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
14ac0 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
14ad0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
14ae0 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
14af0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
14b00 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
14b10 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
14b20 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
14b30 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
14b40 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
14b50 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
14b60 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
14b70 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
14b80 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
14b90 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
14ba0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
14bb0 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
14bc0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14bd0 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
14be0 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45  <dd> ^The SQLITE
14bf0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
14c00 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  S option takes s
14c10 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
14c20 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20 69  f type int,.** i
14c30 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
14c40 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
14c50 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
14c60 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
14c70 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  n of.** memory a
14c80 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
14c90 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d  tics. ^(When mem
14ca0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
14cb0 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a 2a  tatistics are.**
14cc0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 66   disabled, the f
14cd0 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20  ollowing SQLite 
14ce0 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d  interfaces becom
14cf0 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61  e non-operationa
14d00 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20  l:.**   <ul>.** 
14d10 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
14d20 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a  memory_used()].*
14d30 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
14d40 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
14d50 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  er()].**   <li> 
14d60 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
14d70 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
14d80 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
14d90 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a 20  _status64()].** 
14da0 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
14db0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14dc0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
14dd0 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
14de0 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
14df0 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
14e00 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
14e10 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
14e20 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
14e30 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
14e40 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
14e50 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
14e60 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
14e70 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14e80 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
14e90 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14ea0 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
14eb0 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c  ** <dd> ^The SQL
14ec0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
14ed0 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  CH option specif
14ee0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
14ef0 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74 68  ory buffer.** th
14f00 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
14f10 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d 65  e for scratch me
14f20 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20 61  mory.  ^(There a
14f30 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
14f40 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45 5f  ts.** to SQLITE_
14f50 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a 20  CONFIG_SCRATCH: 
14f60 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
14f70 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
14f80 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
14f90 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
14fa0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
14fb0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
14fc0 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
14fd0 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
14fe0 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
14ff0 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
15000 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
15010 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
15020 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72 73  ).)^.** The firs
15030 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
15040 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
15050 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
15060 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
15070 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
15080 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
15090 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 6f   ^SQLite will no
150a0 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e 20  t use more than 
150b0 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66 66  one scratch buff
150c0 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 0a  ers per thread..
150d0 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
150e0 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61 20  never request a 
150f0 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
15100 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
15110 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
15120 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
15130 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  ze..** ^If SQLit
15140 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
15150 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
15160 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
15170 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
15180 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
15190 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
151a0 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
151b0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
151c0 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
151d0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
151e0 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57 68  eeded.<p>.** ^Wh
151f0 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  en the applicati
15200 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79 20  on provides any 
15210 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74 63  amount of scratc
15220 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a 2a  h memory using.*
15230 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
15240 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65 20  SCRATCH, SQLite 
15250 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73 61  avoids unnecessa
15260 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71 6c  ry large.** [sql
15270 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61 70  ite3_malloc|heap
15280 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a 2a   allocations]..*
15290 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70 20  * This can help 
152a0 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70 72  [Robson proof|pr
152b0 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  event memory all
152c0 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 73  ocation failures
152d0 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a 2a  ] due to heap.**
152e0 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 69   fragmentation i
152f0 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d 62  n low-memory emb
15300 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a 2a  edded systems..*
15310 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
15320 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
15330 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51  GECACHE]] <dt>SQ
15340 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
15350 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  CACHE</dt>.** <d
15360 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
15370 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
15380 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
15390 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
153a0 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
153b0 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
153c0 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
153d0 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
153e0 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
153f0 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  .** cache implem
15400 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  entation.  .** T
15410 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
15420 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  n should not be 
15430 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69  used if an appli
15440 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
15450 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
15460 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
15470 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  aded using the [
15480 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15490 41 43 48 45 32 5d 0a 2a 2a 20 63 6f 6e 66 69 67  ACHE2].** config
154a0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 0a  uration option..
154b0 2a 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68  ** ^There are th
154c0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
154d0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
154e0 41 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e  AGECACHE: A poin
154f0 74 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65  ter to.** 8-byte
15500 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f   aligned.** memo
15510 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ry, the size of 
15520 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65 72  each page buffer
15530 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e   (sz), and the n
15540 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20 28  umber of pages (
15550 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
15560 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
15570 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
15580 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
15590 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
155a0 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
155b0 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29  n 512 and 65536)
155c0 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61   plus some extra
155d0 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a   bytes for each.
155e0 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
155f0 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
15600 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64  extra bytes need
15610 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68  ed by the page h
15620 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20  eader.** can be 
15630 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
15640 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
15650 46 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a  FIG_PCACHE_HDRSZ
15660 5d 20 6f 70 74 69 6f 6e 20 0a 2a 2a 20 74 6f 20  ] option .** to 
15670 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
15680 29 5d 2e 0a 2a 2a 20 5e 49 74 20 69 73 20 68 61  )]..** ^It is ha
15690 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72  rmless, apart fr
156a0 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65  om the wasted me
156b0 6d 6f 72 79 2c 0a 2a 2a 20 66 6f 72 20 74 68 65  mory,.** for the
156c0 20 73 7a 20 70 61 72 61 6d 65 74 65 72 20 74 6f   sz parameter to
156d0 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e 20   be larger than 
156e0 6e 65 63 65 73 73 61 72 79 2e 20 20 54 68 65 20  necessary.  The 
156f0 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e  first.** argumen
15700 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 65 72  t should pointer
15710 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c   to an 8-byte al
15720 69 67 6e 65 64 20 62 6c 6f 63 6b 20 6f 66 20 6d  igned block of m
15730 65 6d 6f 72 79 20 74 68 61 74 0a 2a 2a 20 69 73  emory that.** is
15740 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
15750 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2c 20  ytes of memory, 
15760 6f 74 68 65 72 77 69 73 65 20 73 75 62 73 65 71  otherwise subseq
15770 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 69 73  uent behavior is
15780 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
15790 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
157a0 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72  se the memory pr
157b0 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69  ovided by the fi
157c0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
157d0 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d  satisfy its.** m
157e0 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20  emory needs for 
157f0 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65  the first N page
15800 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74  s that it adds t
15810 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64  o cache.  ^If ad
15820 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65  ditional.** page
15830 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73   cache memory is
15840 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77   needed beyond w
15850 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
15860 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20  by this option, 
15870 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67  then.** SQLite g
15880 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  oes to [sqlite3_
15890 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68  malloc()] for th
158a0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f  e additional sto
158b0 72 61 67 65 20 73 70 61 63 65 2e 3c 2f 64 64 3e  rage space.</dd>
158c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
158d0 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
158e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
158f0 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
15900 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
15910 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
15920 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
15930 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
15940 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  r .** that SQLit
15950 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61  e will use for a
15960 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
15970 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
15980 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79  ion needs.** bey
15990 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
159a0 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ed for by [SQLIT
159b0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
159c0 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
159d0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
159e0 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  E]..** ^The SQLI
159f0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
15a00 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
15a10 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
15a20 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  e is compiled.**
15a30 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51   with either [SQ
15a40 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
15a50 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  YS3] or [SQLITE_
15a60 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
15a70 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  and returns.** [
15a80 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
15a90 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69   invoked otherwi
15aa0 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  se..** ^There ar
15ab0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
15ac0 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
15ad0 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38  IG_HEAP:.** An 8
15ae0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
15af0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
15b00 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
15b10 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
15b20 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
15b30 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
15b40 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
15b50 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
15b60 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
15b70 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
15b80 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
15b90 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
15ba0 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
15bb0 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
15bc0 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
15bd0 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
15be0 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
15bf0 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
15c00 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
15c10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
15c20 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
15c30 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
15c40 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  er is not NULL t
15c50 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
15c60 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
15c70 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
15c80 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
15c90 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
15ca0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
15cb0 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
15cc0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
15cd0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
15ce0 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
15cf0 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
15d00 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
15d10 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
15d20 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
15d30 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
15d40 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
15d50 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
15d60 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
15d70 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
15d80 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
15d90 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
15da0 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
15db0 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
15dc0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15dd0 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
15de0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15df0 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
15e00 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
15e10 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74  CONFIG_MUTEX opt
15e20 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15e30 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
15e40 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  h is a.** pointe
15e50 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
15e60 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
15e70 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
15e80 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
15e90 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
15ea0 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65  fies alternative
15eb0 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
15ec0 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
15ed0 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65  used.** in place
15ee0 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
15ef0 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
15f00 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
15f10 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
15f20 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
15f30 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
15f40 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
15f50 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
15f60 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
15f70 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
15f80 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
15f90 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
15fa0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
15fb0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
15fc0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
15fd0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
15fe0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
15ff0 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
16000 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
16010 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
16020 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
16030 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
16040 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
16050 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
16060 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
16070 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
16080 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
16090 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
160a0 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
160b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
160c0 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
160d0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
160e0 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
160f0 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
16100 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
16110 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
16120 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
16130 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
16140 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
16150 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
16160 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16170 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
16180 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
16190 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a  _mutex_methods].
161a0 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
161b0 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
161c0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
161d0 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  d mutex routines
161e0 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
161f0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
16200 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
16210 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
16220 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
16230 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
16240 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
16250 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
16260 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
16270 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
16280 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
16290 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  e.   ^If SQLite 
162a0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
162b0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
162c0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
162d0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
162e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
162f0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
16300 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
16310 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
16320 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
16330 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
16340 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
16350 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
16360 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
16370 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63  ONFIG_GETMUTEX c
16380 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16390 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
163a0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
163b0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
163c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
163d0 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51  OKASIDE]] <dt>SQ
163e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
163f0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
16400 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
16410 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
16420 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
16430 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
16440 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68   determine.** th
16450 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f  e default size o
16460 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  f lookaside memo
16470 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61  ry on each [data
16480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
16490 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
164a0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
164b0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
164c0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
164d0 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
164e0 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
164f0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
16500 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
16510 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16520 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45  ion.)^  ^(SQLITE
16530 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
16540 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69  E.** sets the <i
16550 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
16560 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
16570 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
16580 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
16590 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74  option to [sqlit
165a0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
165b0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
165c0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
165d0 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
165e0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
165f0 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
16600 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
16610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
16620 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
16630 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16640 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
16650 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
16660 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
16670 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
16680 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
16690 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
166a0 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
166b0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
166c0 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
166d0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a  bject specifies.
166e0 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ** the interface
166f0 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
16700 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
16710 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51  tation.)^.** ^SQ
16720 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
16730 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
16740 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
16750 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a  2] object.</dd>.
16760 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
16770 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
16780 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16790 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
167a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
167b0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
167c0 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69  _GETPCACHE2 opti
167d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
167e0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
167f0 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
16800 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
16810 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
16820 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
16830 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68   copies of.** th
16840 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63  e current page c
16850 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
16860 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
16870 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
16880 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16890 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
168a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
168b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
168c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
168d0 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  OG option is use
168e0 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74  d to configure t
168f0 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f  he SQLite.** glo
16900 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e  bal [error log].
16910 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45  .** (^The SQLITE
16920 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
16930 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
16940 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
16950 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
16960 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
16970 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
16980 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
16990 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
169a0 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
169b0 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
169c0 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
169d0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
169e0 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
169f0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
16a00 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
16a10 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
16a20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
16a30 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
16a40 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
16a50 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
16a60 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
16a70 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
16a80 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
16a90 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
16aa0 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
16ab0 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
16ac0 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
16ad0 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
16ae0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
16af0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
16b00 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
16b10 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
16b20 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
16b30 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
16b40 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
16b50 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
16b60 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
16b70 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
16b80 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
16b90 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
16ba0 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
16bb0 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
16bc0 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
16bd0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
16be0 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
16bf0 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
16c00 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
16c10 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
16c20 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
16c30 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
16c40 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
16c50 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
16c60 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
16c70 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
16c80 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
16c90 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
16ca0 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
16cb0 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
16cc0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
16cd0 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
16ce0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
16cf0 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
16d00 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
16d10 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
16d20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
16d30 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
16d40 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
16d50 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
16d60 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16d70 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
16d80 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
16d90 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  dd>^(The SQLITE_
16da0 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f  CONFIG_URI optio
16db0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
16dc0 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
16dd0 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e  e int..** If non
16de0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20  -zero, then URI 
16df0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
16e00 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
16e10 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
16e20 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  s zero,.** then 
16e30 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
16e40 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
16e50 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e  d.)^ ^If URI han
16e60 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
16e70 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c  y.** enabled, al
16e80 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73  l filenames pass
16e90 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
16ea0 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
16eb0 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20  _open_v2()],.** 
16ec0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
16ed0 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
16ee0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
16ef0 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
16f00 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
16f10 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
16f20 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
16f30 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
16f40 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
16f50 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
16f60 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
16f70 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
16f80 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20  ened. ^If it is 
16f90 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
16fa0 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
16fb0 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
16fc0 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
16fd0 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
16fe0 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
16ff0 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
17000 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
17010 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20  is opened. ^(By 
17020 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
17030 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
17040 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
17050 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
17060 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
17070 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
17080 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
17090 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
170a0 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a   defined.)^.**.*
170b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
170c0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
170d0 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49  _SCAN]] <dt>SQLI
170e0 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
170f0 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a  NG_INDEX_SCAN.**
17100 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
17110 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
17120 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69  _INDEX_SCAN opti
17130 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
17140 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67  e integer.** arg
17150 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
17160 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
17170 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
17180 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
17190 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65  sable.** the use
171a0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
171b0 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
171c0 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
171d0 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
171e0 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
171f0 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
17200 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
17210 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
17220 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
17230 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
17240 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
17250 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
17260 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
17270 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
17280 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
17290 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
172a0 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
172b0 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
172c0 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
172d0 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
172e0 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
172f0 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
17300 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
17310 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
17320 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
17330 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
17340 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
17350 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
17360 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
17370 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
17380 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
17390 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
173a0 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
173b0 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
173c0 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
173d0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
173e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
173f0 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
17400 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
17410 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
17420 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
17430 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
17440 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
17450 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
17460 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
17470 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
17480 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
17490 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
174a0 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
174b0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
174c0 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
174d0 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
174e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
174f0 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
17500 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
17510 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
17520 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
17530 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
17540 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
17550 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
17560 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
17570 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
17580 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
17590 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
175a0 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
175b0 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
175c0 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
175d0 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
175e0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
175f0 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
17600 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
17610 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
17620 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
17630 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
17640 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
17650 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
17660 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
17670 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
17680 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
17690 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
176a0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
176b0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
176c0 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
176d0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
176e0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
176f0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
17700 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
17710 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
17720 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
17730 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
17740 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
17750 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
17760 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
17770 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
17780 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
17790 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
177a0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
177b0 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
177c0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
177d0 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
177e0 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
177f0 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
17800 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
17810 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
17820 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
17830 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
17840 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
17850 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
17860 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
17870 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
17880 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
17890 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
178a0 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
178b0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
178c0 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
178d0 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
178e0 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
178f0 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
17900 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
17910 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
17920 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
17930 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
17940 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
17950 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
17960 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
17970 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
17980 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
17990 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
179a0 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
179b0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
179c0 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
179d0 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
179e0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
179f0 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
17a00 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
17a10 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
17a20 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
17a30 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
17a40 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
17a50 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
17a60 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
17a70 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
17a80 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
17a90 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
17aa0 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
17ab0 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
17ac0 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
17ad0 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
17ae0 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
17af0 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
17b00 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69  ze.** will be si
17b10 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
17b20 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f   if necessary so
17b30 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f   that it does no
17b40 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  t exceed the.** 
17b50 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
17b60 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
17b70 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
17b80 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
17b90 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
17ba0 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
17bb0 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
17bc0 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
17bd0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
17be0 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
17bf0 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
17c00 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
17c10 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
17c20 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17c30 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
17c40 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
17c50 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
17c60 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
17c70 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
17c80 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
17c90 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
17ca0 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
17cb0 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
17cc0 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69  d for Windows wi
17cd0 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57  th the [SQLITE_W
17ce0 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65  IN32_MALLOC] pre
17cf0 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
17d00 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51  .** defined. ^SQ
17d10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
17d20 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73  2_HEAPSIZE takes
17d30 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e   a 32-bit unsign
17d40 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  ed integer value
17d50 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69  .** that specifi
17d60 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  es the maximum s
17d70 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74  ize of the creat
17d80 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b  ed heap..**.** [
17d90 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
17da0 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a  CACHE_HDRSZ]].**
17db0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17dc0 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a  IG_PCACHE_HDRSZ.
17dd0 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
17de0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
17df0 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _HDRSZ option ta
17e00 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
17e10 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
17e20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
17e30 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77  an integer and w
17e40 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20  rites into that 
17e50 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62  integer the numb
17e60 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62  er of extra.** b
17e70 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65  ytes per page re
17e80 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20  quired for each 
17e90 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f  page in [SQLITE_
17ea0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
17eb0 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74  ]..** The amount
17ec0 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20   of extra space 
17ed0 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61  required can cha
17ee0 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  nge depending on
17ef0 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a   the compiler,.*
17f00 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72  * target platfor
17f10 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65  m, and SQLite ve
17f20 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rsion..**.** [[S
17f30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
17f40 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
17f50 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a  TE_CONFIG_PMASZ.
17f60 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
17f70 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
17f80 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
17f90 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
17fa0 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75  which.** is an u
17fb0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
17fc0 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69  and sets the "Mi
17fd0 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20  nimum PMA Size" 
17fe0 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72  for the multithr
17ff0 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20  eaded.** sorter 
18000 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  to that integer.
18010 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69    The default mi
18020 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69  nimum PMA Size i
18030 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  s set by the.** 
18040 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50  [SQLITE_SORTER_P
18050 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  MASZ] compile-ti
18060 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20  me option.  New 
18070 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e  threads are laun
18080 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20  ched.** to help 
18090 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74  with sort operat
180a0 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74  ions when multit
180b0 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a  hreaded sorting.
180c0 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75  ** is enabled (u
180d0 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  sing the [PRAGMA
180e0 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e   threads] comman
180f0 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e  d) and the amoun
18100 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20  t of content.** 
18110 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63  to be sorted exc
18120 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69  eeds the page si
18130 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e  ze times the min
18140 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  imum of the.** [
18150 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a  PRAGMA cache_siz
18160 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74  e] setting and t
18170 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 20 3c 2f  his value..** </
18180 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
18190 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
181a0 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a  GLETHREAD  1  /*
181b0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
181c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
181d0 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f  LTITHREAD   2  /
181e0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
181f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
18200 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20  ERIALIZED    3  
18210 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
18220 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18230 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20  MALLOC        4 
18240 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
18250 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
18260 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18270 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20  G_GETMALLOC     
18280 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65  5  /* sqlite3_me
18290 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  m_methods* */.#d
182a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
182b0 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20  FIG_SCRATCH     
182c0 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    6  /* void*, i
182d0 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
182e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
182f0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20  ONFIG_PAGECACHE 
18300 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c      7  /* void*,
18310 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a   int sz, int N *
18320 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18330 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20  _CONFIG_HEAP    
18340 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64        8  /* void
18350 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e  *, int nByte, in
18360 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  t min */.#define
18370 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
18380 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20  EMSTATUS     9  
18390 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64  /* boolean */.#d
183a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
183b0 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20  FIG_MUTEX       
183c0 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   10  /* sqlite3_
183d0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
183e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
183f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
18400 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69       11  /* sqli
18410 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
18420 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75  s* */./* previou
18430 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  sly SQLITE_CONFI
18440 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20  G_CHUNKALLOC 12 
18450 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75  which is now unu
18460 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65  sed. */ .#define
18470 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
18480 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20  OOKASIDE    13  
18490 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  /* int int */.#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 43 41 43 48 45 20 20 20 20 20 20  FIG_PCACHE      
184c0 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f   14  /* no-op */
184d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
184e0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
184f0 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70      15  /* no-op
18500 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18510 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20  TE_CONFIG_LOG   
18520 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46         16  /* xF
18530 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  unc, void* */.#d
18540 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18550 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20  FIG_URI         
18560 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   17  /* int */.#
18570 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18580 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20  NFIG_PCACHE2    
18590 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33    18  /* sqlite3
185a0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
185b0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
185c0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
185d0 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73  ACHE2   19  /* s
185e0 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
185f0 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
18600 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18610 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
18620 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20  SCAN 20  /* int 
18630 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18640 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20  E_CONFIG_SQLLOG 
18650 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71        21  /* xSq
18660 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  llog, void* */.#
18670 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18680 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  NFIG_MMAP_SIZE  
18690 20 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33    22  /* sqlite3
186a0 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f  _int64, sqlite3_
186b0 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65  int64 */.#define
186c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57   SQLITE_CONFIG_W
186d0 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20  IN32_HEAPSIZE   
186e0 20 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42     23  /* int nB
186f0 79 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  yte */.#define S
18700 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
18710 43 48 45 5f 48 44 52 53 5a 20 20 20 20 20 20 20  CHE_HDRSZ       
18720 20 32 34 20 20 2f 2a 20 69 6e 74 20 2a 70 73 7a   24  /* int *psz
18730 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18740 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
18750 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35                25
18760 20 20 2f 2a 20 75 6e 73 69 67 6e 65 64 20 69 6e    /* unsigned in
18770 74 20 73 7a 50 6d 61 20 2a 2f 0a 0a 2f 2a 0a 2a  t szPma */../*.*
18780 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
18790 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20  base Connection 
187a0 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
187b0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
187c0 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
187d0 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  the available in
187e0 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74  teger configurat
187f0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  ion options that
18800 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65  .** can be passe
18810 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
18820 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
18830 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
18840 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
18850 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
18860 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
18870 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
18880 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
18890 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
188a0 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
188b0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
188c0 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
188d0 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
188e0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
188f0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
18900 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
18910 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  _db_config()] to
18920 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
18930 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
18940 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74  ed.  ^The [sqlit
18950 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
18960 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
18970 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
18980 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
18990 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
189a0 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
189b0 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
189c0 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
189d0 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
189e0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
189f0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
18a00 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
18a10 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
18a20 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e  s three addition
18a30 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  al arguments tha
18a40 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
18a50 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d  .** [lookaside m
18a60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d  emory allocator]
18a70 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
18a80 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  or the [database
18a90 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
18aa0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
18ab0 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20  ment (the third 
18ac0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
18ad0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
18ae0 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74  )] is a.** point
18af0 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62  er to a memory b
18b00 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72  uffer to use for
18b10 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
18b20 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  y..** ^The first
18b30 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20   argument after 
18b40 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  the SQLITE_DBCON
18b50 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65  FIG_LOOKASIDE ve
18b60 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c  rb.** may be NUL
18b70 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  L in which case 
18b80 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f  SQLite will allo
18b90 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b  cate the.** look
18ba0 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73  aside buffer its
18bb0 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  elf using [sqlit
18bc0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54  e3_malloc()]. ^T
18bd0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
18be0 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a  nt is the.** siz
18bf0 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73  e of each lookas
18c00 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e  ide buffer slot.
18c10 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67    ^The third arg
18c20 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d  ument is the num
18c30 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e  ber of.** slots.
18c40 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68    The size of th
18c50 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20  e buffer in the 
18c60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
18c70 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74  ust be greater t
18c80 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20  han.** or equal 
18c90 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f  to the product o
18ca0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64  f the second and
18cb0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73   third arguments
18cc0 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a  .  The buffer.**
18cd0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
18ce0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
18cf0 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65  undary.  ^If the
18d00 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
18d10 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42   to.** SQLITE_DB
18d20 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
18d30 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70   is not a multip
18d40 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69  le of 8, it is i
18d50 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75  nternally.** rou
18d60 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65  nded down to the
18d70 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75   next smaller mu
18d80 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28  ltiple of 8.  ^(
18d90 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  The lookaside me
18da0 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  mory.** configur
18db0 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61  ation for a data
18dc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18dd0 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e  can only be chan
18de0 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a  ged when that.**
18df0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e   connection is n
18e00 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69  ot currently usi
18e10 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  ng lookaside mem
18e20 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72  ory, or in other
18e30 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74   words.** when t
18e40 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75  he "current valu
18e50 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  e" returned by.*
18e60 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74  * [sqlite3_db_st
18e70 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f  atus](D,[SQLITE_
18e80 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
18e90 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a  ],...) is zero..
18ea0 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
18eb0 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
18ec0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
18ed0 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e  nfiguration when
18ee0 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65   lookaside.** me
18ef0 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c  mory is in use l
18f00 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67  eaves the config
18f10 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65  uration unchange
18f20 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a  d and returns .*
18f30 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e  * [SQLITE_BUSY].
18f40 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  )^</dd>.**.** <d
18f50 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
18f60 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64  G_ENABLE_FKEY</d
18f70 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
18f80 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
18f90 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
18fa0 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65  able the enforce
18fb0 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65  ment of.** [fore
18fc0 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69  ign key constrai
18fd0 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f  nts].  There sho
18fe0 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
18ff0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
19000 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
19010 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
19020 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
19030 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e  to disable FK en
19040 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f  forcement,.** po
19050 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65  sitive to enable
19060 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
19070 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c  or negative to l
19080 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  eave FK enforcem
19090 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64  ent.** unchanged
190a0 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
190b0 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
190c0 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
190d0 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
190e0 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
190f0 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
19100 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63  hether FK enforc
19110 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20  ement is off or 
19120 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  on.** following 
19130 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
19140 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
19150 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
19160 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
19170 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20  ich case the FK 
19180 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74  enforcement sett
19190 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72  ing is not repor
191a0 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a  ted back. </dd>.
191b0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
191c0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
191d0 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a  _TRIGGER</dt>.**
191e0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
191f0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
19200 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
19210 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
19220 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20  | triggers]..** 
19230 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20  There should be 
19240 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61  two additional a
19250 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65  rguments..** The
19260 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
19270 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  is an integer wh
19280 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61  ich is 0 to disa
19290 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a  ble triggers,.**
192a0 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
192b0 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20  ble triggers or 
192c0 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76  negative to leav
192d0 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e  e the setting un
192e0 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20  changed..** The 
192f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
19300 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
19310 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f   an integer into
19320 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69   which.** is wri
19330 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69  tten 0 or 1 to i
19340 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20  ndicate whether 
19350 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73  triggers are dis
19360 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
19370 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
19380 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
19390 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
193a0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
193b0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
193c0 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67  h case the trigg
193d0 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  er setting is no
193e0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
193f0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
19400 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
19410 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
19420 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30  OKASIDE       10
19430 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74  01  /* void* int
19440 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
19450 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
19460 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20  ENABLE_FKEY     
19470 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74  1002  /* int int
19480 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
19490 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
194a0 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30  BLE_TRIGGER  100
194b0 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a  3  /* int int* *
194c0 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  /.../*.** CAPI3R
194d0 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
194e0 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52  sable Extended R
194f0 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4d  esult Codes.** M
19500 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
19510 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19520 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
19530 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e  t_codes() routin
19540 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  e enables or dis
19550 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78  ables the.** [ex
19560 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
19570 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20  des] feature of 
19580 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74  SQLite. ^The ext
19590 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20  ended result.** 
195a0 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c  codes are disabl
195b0 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f  ed by default fo
195c0 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d  r historical com
195d0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53  patibility..*/.S
195e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
195f0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
19600 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
19610 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
19620 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
19630 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19640 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
19650 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
19660 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
19670 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
19680 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
19690 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
196a0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
196b0 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
196c0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
196d0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
196e0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
196f0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
19700 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
19710 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
19720 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
19730 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
19740 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
19750 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
19760 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
19770 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
19780 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
19790 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
197a0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
197b0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
197c0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
197d0 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
197e0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
197f0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
19800 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
19810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
19820 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
19830 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
19840 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
19850 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
19860 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
19870 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
19880 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
19890 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
198a0 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
198b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
198c0 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
198d0 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
198e0 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
198f0 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
19900 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
19910 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
19920 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
19930 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
19940 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
19950 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19960 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
19970 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
19980 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
19990 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
199a0 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
199b0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
199c0 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
199d0 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
199e0 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
199f0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
19a00 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
19a10 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
19a20 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
19a30 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
19a40 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
19a50 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
19a60 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
19a70 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
19a80 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
19a90 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
19aa0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19ab0 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
19ac0 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
19ad0 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
19ae0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
19af0 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
19b00 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
19b10 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
19b20 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
19b30 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
19b40 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
19b50 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
19b60 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
19b70 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
19b80 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
19b90 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
19ba0 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
19bb0 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
19bc0 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
19bd0 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
19be0 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
19bf0 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
19c00 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
19c10 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
19c20 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
19c30 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
19c40 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
19c50 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
19c60 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
19c70 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
19c80 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
19c90 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
19ca0 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
19cb0 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
19cc0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
19cd0 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
19ce0 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
19cf0 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
19d00 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
19d10 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
19d20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
19d30 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
19d40 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
19d50 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
19d60 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
19d70 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
19d80 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
19d90 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
19da0 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
19db0 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
19dc0 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
19dd0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
19de0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
19df0 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
19e00 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
19e10 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
19e20 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
19e30 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
19e40 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
19e50 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
19e60 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
19e70 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
19e80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
19e90 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
19ea0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
19eb0 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
19ec0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
19ed0 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
19ee0 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
19ef0 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
19f00 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19f10 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
19f20 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19f30 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
19f40 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
19f50 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
19f60 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
19f70 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
19f80 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
19f90 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
19fa0 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45  te3_int64 SQLITE
19fb0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
19fc0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
19fd0 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  id(sqlite3*);../
19fe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
19ff0 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20  ount The Number 
1a000 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
1a010 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1a020 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1a030 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1a040 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
1a050 6f 77 73 20 6d 6f 64 69 66 69 65 64 2c 20 69 6e  ows modified, in
1a060 73 65 72 74 65 64 20 6f 72 0a 2a 2a 20 64 65 6c  serted or.** del
1a070 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
1a080 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
1a090 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ted INSERT, UPDA
1a0a0 54 45 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  TE or DELETE.** 
1a0b0 73 74 61 74 65 6d 65 6e 74 20 6f 6e 20 74 68 65  statement on the
1a0c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a0d0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 64 20 62  tion specified b
1a0e0 79 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  y the only param
1a0f0 65 74 65 72 2e 0a 2a 2a 20 5e 45 78 65 63 75 74  eter..** ^Execut
1a100 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79  ing any other ty
1a110 70 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  pe of SQL statem
1a120 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 6d 6f 64  ent does not mod
1a130 69 66 79 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  ify the value.**
1a140 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69   returned by thi
1a150 73 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  s function..**.*
1a160 2a 20 5e 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20  * ^Only changes 
1a170 6d 61 64 65 20 64 69 72 65 63 74 6c 79 20 62 79  made directly by
1a180 20 74 68 65 20 49 4e 53 45 52 54 2c 20 55 50 44   the INSERT, UPD
1a190 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73 74  ATE or DELETE st
1a1a0 61 74 65 6d 65 6e 74 20 61 72 65 0a 2a 2a 20 63  atement are.** c
1a1b0 6f 6e 73 69 64 65 72 65 64 20 2d 20 61 75 78 69  onsidered - auxi
1a1c0 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
1a1d0 75 73 65 64 20 62 79 20 5b 43 52 45 41 54 45 20  used by [CREATE 
1a1e0 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
1a1f0 72 73 5d 2c 20 0a 2a 2a 20 5b 66 6f 72 65 69 67  rs], .** [foreig
1a200 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 6f  n key actions] o
1a210 72 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  r [REPLACE] cons
1a220 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
1a230 6e 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  n are not counte
1a240 64 2e 0a 2a 2a 20 0a 2a 2a 20 43 68 61 6e 67 65  d..** .** Change
1a250 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
1a260 20 61 72 65 20 69 6e 74 65 72 63 65 70 74 65 64   are intercepted
1a270 20 62 79 20 0a 2a 2a 20 5b 49 4e 53 54 45 41 44   by .** [INSTEAD
1a280 20 4f 46 20 74 72 69 67 67 65 72 20 7c 20 49 4e   OF trigger | IN
1a290 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
1a2a0 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74  s] are not count
1a2b0 65 64 2e 20 5e 54 68 65 20 76 61 6c 75 65 20 0a  ed. ^The value .
1a2c0 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
1a2d0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1a2e0 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
1a2f0 65 72 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50  er an INSERT, UP
1a300 44 41 54 45 20 6f 72 20 0a 2a 2a 20 44 45 4c 45  DATE or .** DELE
1a310 54 45 20 73 74 61 74 65 6d 65 6e 74 20 72 75 6e  TE statement run
1a320 20 6f 6e 20 61 20 76 69 65 77 20 69 73 20 61 6c   on a view is al
1a330 77 61 79 73 20 7a 65 72 6f 2e 20 4f 6e 6c 79 20  ways zero. Only 
1a340 63 68 61 6e 67 65 73 20 6d 61 64 65 20 74 6f 20  changes made to 
1a350 72 65 61 6c 20 0a 2a 2a 20 74 61 62 6c 65 73 20  real .** tables 
1a360 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a  are counted..**.
1a370 2a 2a 20 54 68 69 6e 67 73 20 61 72 65 20 6d 6f  ** Things are mo
1a380 72 65 20 63 6f 6d 70 6c 69 63 61 74 65 64 20 69  re complicated i
1a390 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  f the sqlite3_ch
1a3a0 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e  anges() function
1a3b0 20 69 73 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   is.** executed 
1a3c0 77 68 69 6c 65 20 61 20 74 72 69 67 67 65 72 20  while a trigger 
1a3d0 70 72 6f 67 72 61 6d 20 69 73 20 72 75 6e 6e 69  program is runni
1a3e0 6e 67 2e 20 54 68 69 73 20 6d 61 79 20 68 61 70  ng. This may hap
1a3f0 70 65 6e 20 69 66 20 74 68 65 0a 2a 2a 20 70 72  pen if the.** pr
1a400 6f 67 72 61 6d 20 75 73 65 73 20 74 68 65 20 5b  ogram uses the [
1a410 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1a420 6e 63 74 69 6f 6e 5d 2c 20 6f 72 20 69 66 20 73  nction], or if s
1a430 6f 6d 65 20 6f 74 68 65 72 20 63 61 6c 6c 62 61  ome other callba
1a440 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ck.** function i
1a450 6e 76 6f 6b 65 73 20 73 71 6c 69 74 65 33 5f 63  nvokes sqlite3_c
1a460 68 61 6e 67 65 73 28 29 20 64 69 72 65 63 74 6c  hanges() directl
1a470 79 2e 20 45 73 73 65 6e 74 69 61 6c 6c 79 3a 0a  y. Essentially:.
1a480 2a 2a 20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  ** .** <ul>.**  
1a490 20 3c 6c 69 3e 20 5e 28 42 65 66 6f 72 65 20 65   <li> ^(Before e
1a4a0 6e 74 65 72 69 6e 67 20 61 20 74 72 69 67 67 65  ntering a trigge
1a4b0 72 20 70 72 6f 67 72 61 6d 20 74 68 65 20 76 61  r program the va
1a4c0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 0a  lue returned by.
1a4d0 2a 2a 20 20 20 20 20 20 20 20 73 71 6c 69 74 65  **        sqlite
1a4e0 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  3_changes() func
1a4f0 74 69 6f 6e 20 69 73 20 73 61 76 65 64 2e 20 41  tion is saved. A
1a500 66 74 65 72 20 74 68 65 20 74 72 69 67 67 65 72  fter the trigger
1a510 20 70 72 6f 67 72 61 6d 20 0a 2a 2a 20 20 20 20   program .**    
1a520 20 20 20 20 68 61 73 20 66 69 6e 69 73 68 65 64      has finished
1a530 2c 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 76  , the original v
1a540 61 6c 75 65 20 69 73 20 72 65 73 74 6f 72 65 64  alue is restored
1a550 2e 29 5e 0a 2a 2a 20 0a 2a 2a 20 20 20 3c 6c 69  .)^.** .**   <li
1a560 3e 20 5e 28 57 69 74 68 69 6e 20 61 20 74 72 69  > ^(Within a tri
1a570 67 67 65 72 20 70 72 6f 67 72 61 6d 20 65 61 63  gger program eac
1a580 68 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  h INSERT, UPDATE
1a590 20 61 6e 64 20 44 45 4c 45 54 45 20 0a 2a 2a 20   and DELETE .** 
1a5a0 20 20 20 20 20 20 20 73 74 61 74 65 6d 65 6e 74         statement
1a5b0 20 73 65 74 73 20 74 68 65 20 76 61 6c 75 65 20   sets the value 
1a5c0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1a5d0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a  te3_changes() .*
1a5e0 2a 20 20 20 20 20 20 20 20 75 70 6f 6e 20 63 6f  *        upon co
1a5f0 6d 70 6c 65 74 69 6f 6e 20 61 73 20 6e 6f 72 6d  mpletion as norm
1a600 61 6c 2e 20 4f 66 20 63 6f 75 72 73 65 2c 20 74  al. Of course, t
1a610 68 69 73 20 76 61 6c 75 65 20 77 69 6c 6c 20 6e  his value will n
1a620 6f 74 20 69 6e 63 6c 75 64 65 20 0a 2a 2a 20 20  ot include .**  
1a630 20 20 20 20 20 20 61 6e 79 20 63 68 61 6e 67 65        any change
1a640 73 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 73  s performed by s
1a650 75 62 2d 74 72 69 67 67 65 72 73 2c 20 61 73 20  ub-triggers, as 
1a660 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e  the sqlite3_chan
1a670 67 65 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20  ges() .**       
1a680 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 73   value will be s
1a690 61 76 65 64 20 61 6e 64 20 72 65 73 74 6f 72 65  aved and restore
1a6a0 64 20 61 66 74 65 72 20 65 61 63 68 20 73 75 62  d after each sub
1a6b0 2d 74 72 69 67 67 65 72 20 68 61 73 20 72 75 6e  -trigger has run
1a6c0 2e 29 5e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  .)^.** </ul>.** 
1a6d0 0a 2a 2a 20 5e 54 68 69 73 20 6d 65 61 6e 73 20  .** ^This means 
1a6e0 74 68 61 74 20 69 66 20 74 68 65 20 63 68 61 6e  that if the chan
1a6f0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1a700 6f 6e 20 28 6f 72 20 73 69 6d 69 6c 61 72 29 20  on (or similar) 
1a710 69 73 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68  is used.** by th
1a720 65 20 66 69 72 73 74 20 49 4e 53 45 52 54 2c 20  e first INSERT, 
1a730 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45  UPDATE or DELETE
1a740 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1a750 6e 20 61 20 74 72 69 67 67 65 72 2c 20 69 74 20  n a trigger, it 
1a760 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65 20  .** returns the 
1a770 76 61 6c 75 65 20 61 73 20 73 65 74 20 77 68 65  value as set whe
1a780 6e 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 73 74  n the calling st
1a790 61 74 65 6d 65 6e 74 20 62 65 67 61 6e 20 65 78  atement began ex
1a7a0 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20  ecuting..** ^If 
1a7b0 69 74 20 69 73 20 75 73 65 64 20 62 79 20 74 68  it is used by th
1a7c0 65 20 73 65 63 6f 6e 64 20 6f 72 20 73 75 62 73  e second or subs
1a7d0 65 71 75 65 6e 74 20 73 75 63 68 20 73 74 61 74  equent such stat
1a7e0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 61 20 74  ement within a t
1a7f0 72 69 67 67 65 72 20 0a 2a 2a 20 70 72 6f 67 72  rigger .** progr
1a800 61 6d 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65  am, the value re
1a810 74 75 72 6e 65 64 20 72 65 66 6c 65 63 74 73 20  turned reflects 
1a820 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
1a830 77 73 20 6d 6f 64 69 66 69 65 64 20 62 79 20 74  ws modified by t
1a840 68 65 20 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  he .** previous 
1a850 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f  INSERT, UPDATE o
1a860 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
1a870 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
1a880 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 0a 2a  me trigger..**.*
1a890 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
1a8a0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1a8b0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1a8c0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
1a8d0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
1a8e0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e  ], and the [chan
1a8f0 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
1a900 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
1a910 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
1a920 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
1a930 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
1a940 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1a950 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1a960 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
1a970 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
1a980 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
1a990 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
1a9a0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
1a9b0 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  gful..*/.SQLITE_
1a9c0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
1a9d0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
1a9e0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
1a9f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1aa00 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
1aa10 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
1aa20 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
1aa30 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  te3.**.** ^This 
1aa40 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1aa50 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
1aa60 72 20 6f 66 20 72 6f 77 73 20 69 6e 73 65 72 74  r of rows insert
1aa70 65 64 2c 20 6d 6f 64 69 66 69 65 64 20 6f 72 0a  ed, modified or.
1aa80 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 61 6c  ** deleted by al
1aa90 6c 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44  l [INSERT], [UPD
1aaa0 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ATE] or [DELETE]
1aab0 20 73 74 61 74 65 6d 65 6e 74 73 20 63 6f 6d 70   statements comp
1aac0 6c 65 74 65 64 0a 2a 2a 20 73 69 6e 63 65 20 74  leted.** since t
1aad0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1aae0 65 63 74 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65  ection was opene
1aaf0 64 2c 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 6f  d, including tho
1ab00 73 65 20 65 78 65 63 75 74 65 64 20 61 73 0a 2a  se executed as.*
1ab10 2a 20 70 61 72 74 20 6f 66 20 74 72 69 67 67 65  * part of trigge
1ab20 72 20 70 72 6f 67 72 61 6d 73 2e 20 5e 45 78 65  r programs. ^Exe
1ab30 63 75 74 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  cuting any other
1ab40 20 74 79 70 65 20 6f 66 20 53 51 4c 20 73 74 61   type of SQL sta
1ab50 74 65 6d 65 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e  tement.** does n
1ab60 6f 74 20 61 66 66 65 63 74 20 74 68 65 20 76 61  ot affect the va
1ab70 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1ab80 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1ab90 61 6e 67 65 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20  anges()..** .** 
1aba0 5e 43 68 61 6e 67 65 73 20 6d 61 64 65 20 61 73  ^Changes made as
1abb0 20 70 61 72 74 20 6f 66 20 5b 66 6f 72 65 69 67   part of [foreig
1abc0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61  n key actions] a
1abd0 72 65 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74  re included in t
1abe0 68 65 0a 2a 2a 20 63 6f 75 6e 74 2c 20 62 75 74  he.** count, but
1abf0 20 74 68 6f 73 65 20 6d 61 64 65 20 61 73 20 70   those made as p
1ac00 61 72 74 20 6f 66 20 52 45 50 4c 41 43 45 20 63  art of REPLACE c
1ac10 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
1ac20 74 69 6f 6e 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e  tion are.** not.
1ac30 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
1ac40 69 65 77 20 74 68 61 74 20 61 72 65 20 69 6e 74  iew that are int
1ac50 65 72 63 65 70 74 65 64 20 62 79 20 49 4e 53 54  ercepted by INST
1ac60 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 73 20  EAD OF triggers 
1ac70 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
1ac80 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20  ted..** .** See 
1ac90 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
1aca0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  3_changes()] int
1acb0 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
1acc0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
1acd0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
1ace0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
1acf0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
1ad00 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
1ad10 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
1ad20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
1ad30 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1ad40 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
1ad50 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
1ad60 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
1ad70 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
1ad80 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
1ad90 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
1ada0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
1adb0 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  gful..*/.SQLITE_
1adc0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
1add0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74  TDCALL sqlite3_t
1ade0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
1adf0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1ae00 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
1ae10 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
1ae20 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54 48 4f  g Query.** METHO
1ae30 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1ae40 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
1ae50 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
1ae60 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
1ae70 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
1ae80 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
1ae90 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
1aea0 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
1aeb0 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
1aec0 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
1aed0 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
1aee0 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
1aef0 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
1af00 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
1af10 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
1af20 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
1af30 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
1af40 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
1af50 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
1af60 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
1af70 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
1af80 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
1af90 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
1afa0 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
1afb0 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
1afc0 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
1afd0 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
1afe0 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
1aff0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1b000 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
1b010 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b020 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
1b030 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
1b040 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
1b050 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
1b060 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
1b070 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
1b080 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
1b090 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
1b0a0 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
1b0b0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1b0c0 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
1b0d0 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
1b0e0 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
1b0f0 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
1b100 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
1b110 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
1b120 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
1b130 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
1b140 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
1b150 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
1b160 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
1b170 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
1b180 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
1b190 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
1b1a0 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
1b1b0 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
1b1c0 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
1b1d0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
1b1e0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
1b1f0 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
1b200 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
1b210 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
1b220 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
1b230 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
1b240 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
1b250 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
1b260 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
1b270 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
1b280 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
1b290 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b2a0 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
1b2b0 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
1b2c0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
1b2d0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
1b2e0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1b2f0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
1b300 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
1b310 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
1b320 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
1b330 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
1b340 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
1b350 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
1b360 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
1b370 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1b380 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
1b390 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1b3a0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1b3b0 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
1b3c0 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
1b3d0 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
1b3e0 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
1b3f0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
1b400 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
1b410 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
1b420 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1b430 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
1b440 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
1b450 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
1b460 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
1b470 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
1b480 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
1b490 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1b4a0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1b4b0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1b4c0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1b4d0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
1b4e0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
1b4f0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
1b500 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
1b510 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
1b520 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
1b530 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
1b540 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
1b550 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1b560 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
1b570 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1b580 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
1b590 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1b5a0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
1b5b0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
1b5c0 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54  Complete.**.** T
1b5d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1b5e0 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20  e useful during 
1b5f0 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
1b600 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
1b610 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
1b620 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
1b630 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61   seems to form a
1b640 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
1b650 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
1b660 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
1b670 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
1b680 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
1b690 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
1b6a0 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
1b6b0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1b6c0 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
1b6d0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
1b6e0 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
1b6f0 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
1b700 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61  atement.  ^A sta
1b710 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
1b720 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
1b730 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
1b740 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
1b750 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
1b760 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a  a prefix of a.**
1b770 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45   well-formed CRE
1b780 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
1b790 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c  ement.  ^Semicol
1b7a0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62  ons that are emb
1b7b0 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  edded within.** 
1b7c0 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20  string literals 
1b7d0 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69  or quoted identi
1b7e0 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f  fier names or co
1b7f0 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a  mments are not.*
1b800 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f  * independent to
1b810 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70  kens (they are p
1b820 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  art of the token
1b830 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61   in which they a
1b840 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20  re.** embedded) 
1b850 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20  and thus do not 
1b860 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65  count as a state
1b870 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e  ment terminator.
1b880 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a    ^Whitespace.**
1b890 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
1b8a0 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
1b8b0 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
1b8c0 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
1b8d0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1b8e0 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65   return 0 if the
1b8f0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e   statement is in
1b900 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61  complete.  ^If a
1b910 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
1b920 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65  ation fails, the
1b930 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69  n SQLITE_NOMEM i
1b940 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1b950 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1b960 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
1b970 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1b980 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
1b990 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
1b9a0 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
1b9b0 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  t SQL..**.** ^(I
1b9c0 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74  f SQLite has not
1b9d0 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65   been initialize
1b9e0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1b9f0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70  _initialize()] p
1ba00 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f  rior .** to invo
1ba10 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d  king sqlite3_com
1ba20 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73  plete16() then s
1ba30 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
1ba40 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1ba50 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1ba60 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  by sqlite3_compl
1ba70 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61  ete16().  If tha
1ba80 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  t initialization
1ba90 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20   fails,.** then 
1baa0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1bab0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
1bac0 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20  mplete16() will 
1bad0 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72  be non-zero.** r
1bae0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1baf0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1bb00 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d  input SQL is com
1bb10 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  plete.)^.**.** T
1bb20 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1bb30 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
1bb40 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
1bb50 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1bb60 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
1bb70 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1bb80 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1bb90 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
1bba0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1bbb0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
1bbc0 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
1bbd0 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  order..*/.SQLITE
1bbe0 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
1bbf0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1bc00 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63  complete(const c
1bc10 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54  har *sql);.SQLIT
1bc20 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
1bc30 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1bc40 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
1bc50 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
1bc60 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1bc70 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
1bc80 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
1bc90 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
1bca0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 62 75  ** KEYWORDS: {bu
1bcb0 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
1bcc0 61 63 6b 7d 20 7b 62 75 73 79 20 68 61 6e 64 6c  ack} {busy handl
1bcd0 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  er}.** METHOD: s
1bce0 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
1bcf0 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
1bd00 61 6e 64 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f  andler(D,X,P) ro
1bd10 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
1bd20 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
1bd30 0a 2a 2a 20 74 68 61 74 20 6d 69 67 68 74 20 62  .** that might b
1bd40 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  e invoked with a
1bd50 72 67 75 6d 65 6e 74 20 50 20 77 68 65 6e 65 76  rgument P whenev
1bd60 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74  er.** an attempt
1bd70 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
1bd80 73 73 20 61 20 64 61 74 61 62 61 73 65 20 74 61  ss a database ta
1bd90 62 6c 65 20 61 73 73 6f 63 69 61 74 65 64 20 77  ble associated w
1bda0 69 74 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ith.** [database
1bdb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77   connection] D w
1bdc0 68 65 6e 20 61 6e 6f 74 68 65 72 20 74 68 72 65  hen another thre
1bdd0 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73  ad.** or process
1bde0 20 68 61 73 20 74 68 65 20 74 61 62 6c 65 20 6c   has the table l
1bdf0 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71  ocked..** The sq
1be00 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1be10 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  er() interface i
1be20 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
1be30 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ent.** [sqlite3_
1be40 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
1be50 61 6e 64 20 5b 50 52 41 47 4d 41 20 62 75 73 79  and [PRAGMA busy
1be60 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a  _timeout]..**.**
1be70 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1be80 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
1be90 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
1bea0 59 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  Y].** is returne
1beb0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
1bec0 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
1bed0 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
1bee0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1bef0 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
1bf00 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
1bf10 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
1bf20 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
1bf30 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
1bf40 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1bf50 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
1bf60 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
1bf70 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
1bf80 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
1bf90 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
1bfa0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
1bfb0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
1bfc0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
1bfd0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
1bfe0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
1bff0 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
1c000 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
1c010 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1c020 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
1c030 76 6f 6b 65 64 20 70 72 65 76 69 6f 75 73 6c 79  voked previously
1c040 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 6c 6f   for the same lo
1c050 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49  cking event.  ^I
1c060 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61  f the.** busy ca
1c070 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30  llback returns 0
1c080 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69  , then no additi
1c090 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72  onal attempts ar
1c0a0 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63  e made to.** acc
1c0b0 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1c0c0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53   and [SQLITE_BUS
1c0d0 59 5d 20 69 73 20 72 65 74 75 72 6e 65 64 0a 2a  Y] is returned.*
1c0e0 2a 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  * to the applica
1c0f0 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
1c100 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1c110 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
1c120 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
1c130 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 61  .** is made to a
1c140 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
1c150 73 65 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65  se and the cycle
1c160 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20   repeats..**.** 
1c170 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20  The presence of 
1c180 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  a busy handler d
1c190 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65  oes not guarante
1c1a0 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62  e that it will b
1c1b0 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65  e invoked.** whe
1c1c0 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20  n there is lock 
1c1d0 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20  contention. ^If 
1c1e0 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65  SQLite determine
1c1f0 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20  s that invoking 
1c200 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64  the busy.** hand
1c210 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74  ler could result
1c220 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20   in a deadlock, 
1c230 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64  it will go ahead
1c240 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
1c250 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20  ITE_BUSY].** to 
1c260 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1c270 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
1c280 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79  ing the .** busy
1c290 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
1c2a0 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
1c2b0 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
1c2c0 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
1c2d0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
1c2e0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
1c2f0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
1c300 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
1c310 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
1c320 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1c330 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
1c340 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
1c350 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
1c360 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
1c370 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
1c380 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
1c390 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
1c3a0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
1c3b0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
1c3c0 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
1c3d0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
1c3e0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
1c3f0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
1c400 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
1c410 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
1c420 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
1c430 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
1c440 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
1c450 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
1c460 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
1c470 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
1c480 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
1c490 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
1c4a0 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
1c4b0 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
1c4c0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
1c4d0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
1c4e0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
1c4f0 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
1c500 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
1c510 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
1c520 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
1c530 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
1c540 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1c550 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1c560 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1c570 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68  defined for each
1c580 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1c590 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74  nnection].  Sett
1c5a0 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68  ing a new busy h
1c5b0 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e  andler clears an
1c5c0 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  y.** previously 
1c5d0 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20  set handler.)^  
1c5e0 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69  ^Note that calli
1c5f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
1c600 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f  _timeout()].** o
1c610 72 20 65 76 61 6c 75 61 74 69 6e 67 20 5b 50 52  r evaluating [PR
1c620 41 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75  AGMA busy_timeou
1c630 74 3d 4e 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65  t=N] will change
1c640 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e   the.** busy han
1c650 64 6c 65 72 20 61 6e 64 20 74 68 75 73 20 63 6c  dler and thus cl
1c660 65 61 72 20 61 6e 79 20 70 72 65 76 69 6f 75 73  ear any previous
1c670 6c 79 20 73 65 74 20 62 75 73 79 20 68 61 6e 64  ly set busy hand
1c680 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
1c690 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
1c6a0 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
1c6b0 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
1c6c0 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
1c6d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c6e0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1c6f0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
1c700 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
1c710 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e  .** the busy han
1c720 64 6c 65 72 20 69 73 20 6e 6f 74 20 72 65 65 6e  dler is not reen
1c730 74 72 61 6e 74 2e 20 20 41 6e 79 20 73 75 63 68  trant.  Any such
1c740 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
1c750 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
1c760 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
1c770 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
1c780 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
1c790 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1c7a0 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
1c7b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c7c0 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
1c7d0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1c7e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1c7f0 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
1c800 4c 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  L sqlite3_busy_h
1c810 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1c820 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e   int(*)(void*,in
1c830 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  t), void*);../*.
1c840 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
1c850 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a   A Busy Timeout.
1c860 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
1c870 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  e3.**.** ^This r
1c880 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
1c890 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1c8a0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
1c8b0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
1c8c0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
1c8d0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
1c8e0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
1c8f0 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
1c900 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
1c910 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
1c920 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
1c930 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
1c940 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
1c950 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
1c960 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
1c970 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1c980 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1c990 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
1c9a0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
1c9b0 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
1c9c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
1c9d0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
1c9e0 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
1c9f0 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
1ca00 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
1ca10 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
1ca20 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
1ca30 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
1ca40 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
1ca50 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
1ca60 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
1ca70 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
1ca80 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
1ca90 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
1caa0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 61  connection] at a
1cab0 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
1cac0 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
1cad0 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
1cae0 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
1caf0 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1cb00 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
1cb10 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
1cb20 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
1cb30 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
1cb40 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
1cb50 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
1cb60 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73 79  o:  [PRAGMA busy
1cb70 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 53 51 4c  _timeout].*/.SQL
1cb80 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
1cb90 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1cba0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1cbb0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
1cbc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cbd0 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
1cbe0 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
1cbf0 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20  ning Queries.** 
1cc00 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1cc10 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1cc20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1cc30 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1cc40 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1cc50 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1cc60 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1cc70 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1cc80 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1cc90 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1cca0 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1ccb0 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1ccc0 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1ccd0 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1cce0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1ccf0 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1cd00 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1cd10 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1cd20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1cd30 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1cd40 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1cd50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1cd60 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1cd70 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1cd80 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1cd90 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1cda0 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1cdb0 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1cdc0 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1cdd0 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1cde0 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1cdf0 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1ce00 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1ce10 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1ce20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1ce30 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1ce40 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1ce50 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1ce60 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1ce70 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1ce80 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1ce90 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1cea0 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1ceb0 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1cec0 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1ced0 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1cee0 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1cef0 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1cf00 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1cf10 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1cf20 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1cf30 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1cf40 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1cf50 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1cf60 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1cf70 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1cf80 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1cf90 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1cfa0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1cfb0 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1cfc0 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1cfd0 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1cfe0 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1cff0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1d000 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1d010 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1d020 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1d030 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1d040 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1d050 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1d060 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1d070 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1d080 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1d090 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1d0a0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1d0b0 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1d0c0 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1d0d0 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1d0e0 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1d0f0 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1d100 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1d110 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1d120 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1d130 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1d140 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1d150 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1d160 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1d170 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1d180 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1d190 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1d1a0 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1d1b0 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1d1c0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1d1d0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1d1e0 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1d1f0 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1d200 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1d210 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1d220 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1d230 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1d240 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1d250 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1d260 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1d270 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1d280 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1d290 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1d2a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1d2b0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1d2c0 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1d2d0 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1d2e0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1d2f0 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1d300 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1d310 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1d320 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1d330 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1d340 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1d350 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1d360 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1d370 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1d380 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1d390 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1d3a0 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1d3b0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1d3c0 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1d3d0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1d3e0 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1d3f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1d400 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1d410 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1d420 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1d430 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1d440 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1d450 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1d460 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1d470 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1d480 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1d490 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1d4a0 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1d4b0 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1d4c0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1d4d0 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1d4e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1d4f0 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1d500 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1d510 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1d520 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1d530 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1d540 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1d550 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1d560 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1d570 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1d580 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1d590 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1d5a0 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1d5b0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1d5c0 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1d5d0 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1d5e0 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1d5f0 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1d600 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1d610 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1d620 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1d630 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1d640 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1d650 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1d660 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1d670 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1d680 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1d690 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1d6a0 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1d6b0 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1d6c0 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1d6d0 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1d6e0 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1d6f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1d700 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1d710 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1d720 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1d730 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1d740 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1d750 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1d760 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1d770 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1d780 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1d790 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1d7a0 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1d7b0 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1d7c0 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1d7d0 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1d7e0 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1d7f0 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1d800 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1d810 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1d820 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1d830 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1d840 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  g()]..*/.SQLITE_
1d850 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
1d860 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 67  TDCALL sqlite3_g
1d870 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69  et_table(.  sqli
1d880 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1d890 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74    /* An open dat
1d8a0 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  abase */.  const
1d8b0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
1d8c0 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
1d8d0 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61  aluated */.  cha
1d8e0 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20  r ***pazResult, 
1d8f0 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66     /* Results of
1d900 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20   the query */.  
1d910 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20  int *pnRow,     
1d920 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
1d930 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77  of result rows w
1d940 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1d950 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20   int *pnColumn, 
1d960 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1d970 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d   of result colum
1d980 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ns written here 
1d990 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72  */.  char **pzEr
1d9a0 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72  rmsg       /* Er
1d9b0 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
1d9c0 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  here */.);.SQLIT
1d9d0 45 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54  E_API void SQLIT
1d9e0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
1d9f0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
1da00 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
1da10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
1da20 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
1da30 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
1da40 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1da50 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d  utines are work-
1da60 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
1da70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
1da80 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
1da90 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
1daa0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20  d C library..** 
1dab0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 75  These routines u
1dac0 6e 64 65 72 73 74 61 6e 64 20 6d 6f 73 74 20 6f  nderstand most o
1dad0 66 20 74 68 65 20 63 6f 6d 6d 6f 6e 20 4b 26 52  f the common K&R
1dae0 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1daf0 6f 6e 73 2c 0a 2a 2a 20 70 6c 75 73 20 73 6f 6d  ons,.** plus som
1db00 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6e 6f 6e  e additional non
1db10 2d 73 74 61 6e 64 61 72 64 20 66 6f 72 6d 61 74  -standard format
1db20 73 2c 20 64 65 74 61 69 6c 65 64 20 62 65 6c 6f  s, detailed belo
1db30 77 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  w..** Note that 
1db40 73 6f 6d 65 20 6f 66 20 74 68 65 20 6d 6f 72 65  some of the more
1db50 20 6f 62 73 63 75 72 65 20 66 6f 72 6d 61 74 74   obscure formatt
1db60 69 6e 67 20 6f 70 74 69 6f 6e 73 20 66 72 6f 6d  ing options from
1db70 20 72 65 63 65 6e 74 0a 2a 2a 20 43 2d 6c 69 62   recent.** C-lib
1db80 72 61 72 79 20 73 74 61 6e 64 61 72 64 73 20 61  rary standards a
1db90 72 65 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  re omitted from 
1dba0 74 68 69 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74  this implementat
1dbb0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
1dbc0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1dbd0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
1dbe0 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1dbf0 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
1dc00 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
1dc10 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
1dc20 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
1dc30 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
1dc40 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1dc50 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
1dc60 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
1dc70 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
1dc80 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
1dc90 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
1dca0 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
1dcb0 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
1dcc0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
1dcd0 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
1dce0 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
1dcf0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1dd00 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
1dd10 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ng..**.** ^(The 
1dd20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1dd30 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
1dd40 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
1dd50 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
1dd60 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1dd70 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
1dd80 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
1dd90 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
1dda0 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
1ddb0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1ddc0 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
1ddd0 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
1dde0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
1ddf0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
1de00 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
1de10 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
1de20 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
1de30 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
1de40 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
1de50 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
1de60 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
1de70 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
1de80 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
1de90 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1dea0 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
1deb0 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
1dec0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
1ded0 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1dee0 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
1def0 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
1df00 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
1df10 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
1df20 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
1df30 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
1df40 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
1df50 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
1df60 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
1df70 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
1df80 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
1df90 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
1dfa0 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
1dfb0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
1dfc0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1dfd0 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
1dfe0 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
1dff0 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
1e000 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
1e010 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
1e020 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
1e030 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1e040 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
1e050 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
1e060 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
1e070 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
1e080 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1e090 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
1e0a0 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
1e0b0 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
1e0c0 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
1e0d0 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
1e0e0 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
1e0f0 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
1e100 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
1e110 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
1e120 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
1e130 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  acters..**.** ^T
1e140 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  he sqlite3_vsnpr
1e150 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1e160 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73  s a varargs vers
1e170 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1e180 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a  nprintf()..**.**
1e190 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1e1a0 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
1e1b0 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
1e1c0 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
1e1d0 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
1e1e0 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
1e1f0 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
1e200 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
1e210 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
1e220 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
1e230 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
1e240 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
1e250 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
1e260 22 25 51 22 2c 20 22 25 77 22 20 61 6e 64 20 22  "%Q", "%w" and "
1e270 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1e280 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1e290 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1e2a0 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1e2b0 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
1e2c0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1e2d0 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
1e2e0 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
1e2f0 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
1e300 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
1e310 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
1e320 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
1e330 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
1e340 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
1e350 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
1e360 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
1e370 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
1e380 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
1e390 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
1e3a0 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
1e3b0 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
1e3c0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
1e3d0 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
1e3e0 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
1e3f0 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
1e400 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1e410 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1e420 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
1e430 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
1e440 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
1e450 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1e460 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
1e470 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
1e480 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
1e490 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1e4a0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1e4b0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1e4c0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1e4d0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1e4e0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
1e4f0 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
1e500 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1e510 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1e520 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1e530 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1e540 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1e550 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1e560 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
1e570 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
1e580 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
1e590 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
1e5a0 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
1e5b0 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
1e5c0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1e5d0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1e5e0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1e5f0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1e600 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
1e610 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
1e620 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1e630 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
1e640 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
1e650 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
1e660 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
1e670 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
1e680 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
1e690 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
1e6a0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1e6b0 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1e6c0 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1e6d0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1e6e0 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1e6f0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1e700 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
1e710 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
1e720 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
1e730 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
1e740 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
1e750 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
1e760 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
1e770 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
1e780 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
1e790 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
1e7a0 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
1e7b0 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
1e7c0 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
1e7d0 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
1e7e0 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
1e7f0 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
1e800 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
1e810 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
1e820 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
1e830 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
1e840 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1e850 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
1e860 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
1e870 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
1e880 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
1e890 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
1e8a0 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
1e8b0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1e8c0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1e8d0 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1e8e0 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1e8f0 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1e900 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
1e910 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1e920 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1e930 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1e940 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1e950 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1e960 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
1e970 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
1e980 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
1e990 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
1e9a0 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
1e9b0 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
1e9c0 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
1e9d0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1e9e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1e9f0 77 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  w" formatting op
1ea00 74 69 6f 6e 20 69 73 20 6c 69 6b 65 20 22 25 71  tion is like "%q
1ea10 22 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74  " except that it
1ea20 20 65 78 70 65 63 74 73 20 74 6f 0a 2a 2a 20 62   expects to.** b
1ea30 65 20 63 6f 6e 74 61 69 6e 65 64 20 77 69 74 68  e contained with
1ea40 69 6e 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 73  in double-quotes
1ea50 20 69 6e 73 74 65 61 64 20 6f 66 20 73 69 6e 67   instead of sing
1ea60 6c 65 20 71 75 6f 74 65 73 2c 20 61 6e 64 20 69  le quotes, and i
1ea70 74 0a 2a 2a 20 65 73 63 61 70 65 73 20 74 68 65  t.** escapes the
1ea80 20 64 6f 75 62 6c 65 2d 71 75 6f 74 65 20 63 68   double-quote ch
1ea90 61 72 61 63 74 65 72 20 69 6e 73 74 65 61 64 20  aracter instead 
1eaa0 6f 66 20 74 68 65 20 73 69 6e 67 6c 65 2d 71 75  of the single-qu
1eab0 6f 74 65 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  ote.** character
1eac0 2e 29 5e 20 20 54 68 65 20 22 25 77 22 20 66 6f  .)^  The "%w" fo
1ead0 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1eae0 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
1eaf0 73 61 66 65 6c 79 20 69 6e 73 65 72 74 69 6e 67  safely inserting
1eb00 0a 2a 2a 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  .** table and co
1eb10 6c 75 6d 6e 20 6e 61 6d 65 73 20 69 6e 74 6f 20  lumn names into 
1eb20 61 20 63 6f 6e 73 74 72 75 63 74 65 64 20 53 51  a constructed SQ
1eb30 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  L statement..**.
1eb40 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f  ** ^(The "%z" fo
1eb50 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1eb60 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20  works like "%s" 
1eb70 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  but with the.** 
1eb80 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
1eb90 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
1eba0 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
1ebb0 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
1ebc0 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
1ebd0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
1ebe0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
1ebf0 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f  put string.)^.*/
1ec00 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1ec10 20 2a 53 51 4c 49 54 45 5f 43 44 45 43 4c 20 73   *SQLITE_CDECL s
1ec20 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
1ec30 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
1ec40 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1ec50 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
1ec60 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
1ec70 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
1ec80 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f  a_list);.SQLITE_
1ec90 41 50 49 20 63 68 61 72 20 2a 53 51 4c 49 54 45  API char *SQLITE
1eca0 5f 43 44 45 43 4c 20 73 71 6c 69 74 65 33 5f 73  _CDECL sqlite3_s
1ecb0 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1ecc0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1ecd0 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
1ece0 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
1ecf0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 73 6e  CALL sqlite3_vsn
1ed00 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1ed10 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  ,const char*, va
1ed20 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _list);../*.** C
1ed30 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1ed40 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
1ed50 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
1ed60 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
1ed70 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
1ed80 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
1ed90 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
1eda0 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
1edb0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
1edc0 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
1edd0 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
1ede0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
1edf0 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
1ee00 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
1ee10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1ee20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
1ee30 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
1ee40 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1ee50 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
1ee60 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
1ee70 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1ee80 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
1ee90 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1eea0 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
1eeb0 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
1eec0 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
1eed0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1eee0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1eef0 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
1ef00 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
1ef10 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
1ef20 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
1ef30 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
1ef40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1ef50 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
1ef60 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
1ef70 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
1ef80 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
1ef90 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
1efa0 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
1efb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1efc0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1efd0 33 5f 6d 61 6c 6c 6f 63 36 34 28 4e 29 20 72 6f  3_malloc64(N) ro
1efe0 75 74 69 6e 65 20 77 6f 72 6b 73 20 6a 75 73 74  utine works just
1eff0 20 6c 69 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33   like.** sqlite3
1f000 5f 6d 61 6c 6c 6f 63 28 4e 29 20 65 78 63 65 70  _malloc(N) excep
1f010 74 20 74 68 61 74 20 4e 20 69 73 20 61 6e 20 75  t that N is an u
1f020 6e 73 69 67 6e 65 64 20 36 34 2d 62 69 74 20 69  nsigned 64-bit i
1f030 6e 74 65 67 65 72 20 69 6e 73 74 65 61 64 0a 2a  nteger instead.*
1f040 2a 20 6f 66 20 61 20 73 69 67 6e 65 64 20 33 32  * of a signed 32
1f050 2d 62 69 74 20 69 6e 74 65 67 65 72 2e 0a 2a 2a  -bit integer..**
1f060 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
1f070 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
1f080 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
1f090 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
1f0a0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
1f0b0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1f0c0 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
1f0d0 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
1f0e0 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
1f0f0 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
1f100 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
1f110 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
1f120 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
1f130 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
1f140 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
1f150 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
1f160 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
1f170 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
1f180 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
1f190 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
1f1a0 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
1f1b0 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
1f1c0 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
1f1d0 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
1f1e0 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
1f1f0 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
1f200 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1f210 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
1f220 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
1f230 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
1f240 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
1f250 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
1f260 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
1f270 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
1f280 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
1f290 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1f2a0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
1f2b0 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
1f2c0 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
1f2d0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f2e0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1f2f0 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  lloc()..**.** ^T
1f300 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  he sqlite3_reall
1f310 6f 63 28 58 2c 4e 29 20 69 6e 74 65 72 66 61 63  oc(X,N) interfac
1f320 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  e attempts to re
1f330 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20  size a.** prior 
1f340 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f350 6e 20 58 20 74 6f 20 62 65 20 61 74 20 6c 65 61  n X to be at lea
1f360 73 74 20 4e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  st N bytes..** ^
1f370 49 66 20 74 68 65 20 58 20 70 61 72 61 6d 65 74  If the X paramet
1f380 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1f390 61 6c 6c 6f 63 28 58 2c 4e 29 0a 2a 2a 20 69 73  alloc(X,N).** is
1f3a0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1f3b0 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f  then its behavio
1f3c0 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74  r is identical t
1f3d0 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c  o calling.** sql
1f3e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 2e 0a  ite3_malloc(N)..
1f3f0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 20 70 61 72  ** ^If the N par
1f400 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1f410 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69  3_realloc(X,N) i
1f420 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
1f430 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
1f440 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
1f450 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
1f460 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1f470 33 5f 66 72 65 65 28 58 29 2e 0a 2a 2a 20 5e 73  3_free(X)..** ^s
1f480 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58  qlite3_realloc(X
1f490 2c 4e 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ,N) returns a po
1f4a0 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1f4b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1f4c0 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1f4d0 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1f4e0 55 4c 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69  ULL if insuffici
1f4f0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 61 76  ent memory is av
1f500 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1f510 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1f520 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1f530 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1f540 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1f550 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1f560 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1f570 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1f580 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1f590 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1f5a0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e  ite3_realloc(X,N
1f5b0 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1f5c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1f5d0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1f5e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1f5f0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
1f600 64 20 4e 20 69 73 20 70 6f 73 69 74 69 76 65 2c  d N is positive,
1f610 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 70 72 69   then the.** pri
1f620 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73  or allocation is
1f630 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a   not freed..**.*
1f640 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
1f650 65 61 6c 6c 6f 63 36 34 28 58 2c 4e 29 20 69 6e  ealloc64(X,N) in
1f660 74 65 72 66 61 63 65 73 20 77 6f 72 6b 73 20 74  terfaces works t
1f670 68 65 20 73 61 6d 65 20 61 73 0a 2a 2a 20 73 71  he same as.** sq
1f680 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c  lite3_realloc(X,
1f690 4e 29 20 65 78 63 65 70 74 20 74 68 61 74 20 4e  N) except that N
1f6a0 20 69 73 20 61 20 36 34 2d 62 69 74 20 75 6e 73   is a 64-bit uns
1f6b0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 69 6e  igned integer in
1f6c0 73 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 33 32  stead.** of a 32
1f6d0 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
1f6e0 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 58  ger..**.** ^If X
1f6f0 20 69 73 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   is a memory all
1f700 6f 63 61 74 69 6f 6e 20 70 72 65 76 69 6f 75 73  ocation previous
1f710 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
1f720 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f730 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ),.** sqlite3_ma
1f740 6c 6c 6f 63 36 34 28 29 2c 20 73 71 6c 69 74 65  lloc64(), sqlite
1f750 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 20 6f 72 20  3_realloc(), or 
1f760 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36  sqlite3_realloc6
1f770 34 28 29 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  4(), then.** sql
1f780 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65  ite3_msize(X) re
1f790 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
1f7a0 66 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 61 6c  f that memory al
1f7b0 6c 6f 63 61 74 69 6f 6e 20 69 6e 20 62 79 74 65  location in byte
1f7c0 73 2e 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  s..** ^The value
1f7d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
1f7e0 69 74 65 33 5f 6d 73 69 7a 65 28 58 29 20 6d 69  ite3_msize(X) mi
1f7f0 67 68 74 20 62 65 20 6c 61 72 67 65 72 20 74 68  ght be larger th
1f800 61 6e 20 74 68 65 20 6e 75 6d 62 65 72 0a 2a 2a  an the number.**
1f810 20 6f 66 20 62 79 74 65 73 20 72 65 71 75 65 73   of bytes reques
1f820 74 65 64 20 77 68 65 6e 20 58 20 77 61 73 20 61  ted when X was a
1f830 6c 6c 6f 63 61 74 65 64 2e 20 20 5e 49 66 20 58  llocated.  ^If X
1f840 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1f850 65 72 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  er then.** sqlit
1f860 65 33 5f 6d 73 69 7a 65 28 58 29 20 72 65 74 75  e3_msize(X) retu
1f870 72 6e 73 20 7a 65 72 6f 2e 20 20 49 66 20 58 20  rns zero.  If X 
1f880 70 6f 69 6e 74 73 20 74 6f 20 73 6f 6d 65 74 68  points to someth
1f890 69 6e 67 20 74 68 61 74 20 69 73 20 6e 6f 74 0a  ing that is not.
1f8a0 2a 2a 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  ** the beginning
1f8b0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   of memory alloc
1f8c0 61 74 69 6f 6e 2c 20 6f 72 20 69 66 20 69 74 20  ation, or if it 
1f8d0 70 6f 69 6e 74 73 20 74 6f 20 61 20 66 6f 72 6d  points to a form
1f8e0 65 72 6c 79 0a 2a 2a 20 76 61 6c 69 64 20 6d 65  erly.** valid me
1f8f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1f900 74 68 61 74 20 68 61 73 20 6e 6f 77 20 62 65 65  that has now bee
1f910 6e 20 66 72 65 65 64 2c 20 74 68 65 6e 20 74 68  n freed, then th
1f920 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
1f930 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1f940 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  ) is undefined a
1f950 6e 64 20 70 6f 73 73 69 62 6c 79 20 68 61 72 6d  nd possibly harm
1f960 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ful..**.** ^The 
1f970 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
1f980 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1f990 63 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 61  c(), sqlite3_rea
1f9a0 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  lloc(),.** sqlit
1f9b0 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20 61  e3_malloc64(), a
1f9c0 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
1f9d0 6f 63 36 34 28 29 0a 2a 2a 20 69 73 20 61 6c 77  oc64().** is alw
1f9e0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
1f9f0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
1fa00 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
1fa10 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
1fa20 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
1fa30 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
1fa40 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
1fa50 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
1fa60 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
1fa70 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
1fa80 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
1fa90 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
1faa0 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
1fab0 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
1fac0 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
1fad0 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
1fae0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
1faf0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
1fb00 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
1fb10 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
1fb20 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
1fb30 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
1fb40 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
1fb50 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
1fb60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
1fb70 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
1fb80 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
1fb90 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1fba0 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77  7.10, the Window
1fbb0 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
1fbc0 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  ayer called.** t
1fbd0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
1fbe0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
1fbf0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
1fc00 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
1fc10 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
1fc20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
1fc30 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
1fc40 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
1fc50 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
1fc60 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
1fc70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
1fc80 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
1fc90 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
1fca0 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72  ation errors wer
1fcb0 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
1fcc0 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70  ** they were rep
1fcd0 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
1fce0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
1fcf0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
1fd00 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
1fd10 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
1fd20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1fd30 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
1fd40 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1fd50 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1fd60 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
1fd70 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
1fd80 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
1fd90 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1fda0 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
1fdb0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1fdc0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
1fdd0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1fde0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
1fdf0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
1fe00 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
1fe10 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
1fe20 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
1fe30 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
1fe40 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
1fe50 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
1fe60 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
1fe70 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1fe80 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
1fe90 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
1fea0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1feb0 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
1fec0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ALL sqlite3_mall
1fed0 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  oc(int);.SQLITE_
1fee0 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45  API void *SQLITE
1fef0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
1ff00 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69 74 65  _malloc64(sqlite
1ff10 33 5f 75 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  3_uint64);.SQLIT
1ff20 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c 49  E_API void *SQLI
1ff30 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
1ff40 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a  e3_realloc(void*
1ff50 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
1ff60 50 49 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  PI void *SQLITE_
1ff70 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
1ff80 72 65 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c  realloc64(void*,
1ff90 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29   sqlite3_uint64)
1ffa0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1ffb0 64 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  d SQLITE_STDCALL
1ffc0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
1ffd0 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  id*);.SQLITE_API
1ffe0 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20   sqlite3_uint64 
1fff0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
20000 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 76 6f 69  qlite3_msize(voi
20010 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
20020 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
20030 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
20040 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
20050 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
20060 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
20070 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
20080 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
20090 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
200a0 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
200b0 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
200c0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
200d0 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
200e0 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
200f0 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
20100 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
20110 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
20120 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
20130 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
20140 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
20150 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
20160 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
20170 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
20180 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
20190 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
201a0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
201b0 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
201c0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
201d0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
201e0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
201f0 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
20200 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
20210 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
20220 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
20230 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
20240 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
20250 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
20260 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
20270 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
20280 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
20290 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
202a0 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
202b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
202c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
202d0 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
202e0 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
202f0 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
20300 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
20310 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
20320 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
20330 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
20340 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
20350 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
20360 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
20370 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
20380 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
20390 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
203a0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
203b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
203c0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
203d0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
203e0 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
203f0 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
20400 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
20410 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
20420 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
20430 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
20440 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
20450 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
20460 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54 45  te3_int64 SQLITE
20470 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
20480 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
20490 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  d);.SQLITE_API s
204a0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c  qlite3_int64 SQL
204b0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
204c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
204d0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
204e0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
204f0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
20500 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
20510 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
20520 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
20530 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
20540 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
20550 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
20560 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
20570 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
20580 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
20590 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
205a0 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
205b0 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
205c0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
205d0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
205e0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
205f0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
20600 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
20610 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
20620 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
20630 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
20640 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
20650 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
20660 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
20670 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
20680 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
20690 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
206a0 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
206b0 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
206c0 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
206d0 65 72 20 50 2e 0a 2a 2a 20 5e 54 68 65 20 50 20  er P..** ^The P 
206e0 70 61 72 61 6d 65 74 65 72 20 63 61 6e 20 62 65  parameter can be
206f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
20700 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73 20  .**.** ^If this 
20710 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74 20  routine has not 
20720 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79 20  been previously 
20730 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68 65  called or if the
20740 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61 6c   previous.** cal
20750 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68 61  l had N less tha
20760 6e 20 6f 6e 65 20 6f 72 20 61 20 4e 55 4c 4c 20  n one or a NULL 
20770 70 6f 69 6e 74 65 72 20 66 6f 72 20 50 2c 20 74  pointer for P, t
20780 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69 73 0a  hen the PRNG is.
20790 2a 2a 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  ** seeded using 
207a0 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
207b0 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78 52 61  ned from the xRa
207c0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
207d0 6f 66 0a 2a 2a 20 74 68 65 20 64 65 66 61 75 6c  of.** the defaul
207e0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
207f0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74  object..** ^If t
20800 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
20810 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
20820 20 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f   had an N of 1 o
20830 72 20 6d 6f 72 65 20 61 6e 64 20 61 0a 2a 2a 20  r more and a.** 
20840 6e 6f 6e 2d 4e 55 4c 4c 20 50 20 74 68 65 6e 20  non-NULL P then 
20850 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
20860 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
20870 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
20880 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
20890 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
208a0 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
208b0 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
208c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
208d0 76 6f 69 64 20 53 51 4c 49 54 45 5f 53 54 44 43  void SQLITE_STDC
208e0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 72 61 6e 64  ALL sqlite3_rand
208f0 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f  omness(int N, vo
20900 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id *P);../*.** C
20910 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
20920 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74  -Time Authorizat
20930 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
20940 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
20950 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
20960 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20 61  tine registers a
20970 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  n authorizer cal
20980 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61 72  lback with a par
20990 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
209a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
209b0 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68  , supplied in th
209c0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
209d0 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72  ..** ^The author
209e0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
209f0 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20   invoked as SQL 
20a00 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62  statements are b
20a10 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  eing compiled.**
20a20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   by [sqlite3_pre
20a30 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76  pare()] or its v
20a40 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33  ariants [sqlite3
20a50 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a  _prepare_v2()],.
20a60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
20a70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71  are16()] and [sq
20a80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
20a90 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69  v2()].  ^At vari
20aa0 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75  ous.** points du
20ab0 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61  ring the compila
20ac0 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73  tion process, as
20ad0 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20   logic is being 
20ae0 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65  created.** to pe
20af0 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63  rform various ac
20b00 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f  tions, the autho
20b10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
20b20 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20  s invoked to.** 
20b30 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63 74  see if those act
20b40 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64  ions are allowed
20b50 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  .  ^The authoriz
20b60 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75  er callback shou
20b70 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ld.** return [SQ
20b80 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f  LITE_OK] to allo
20b90 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53  w the action, [S
20ba0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f  QLITE_IGNORE] to
20bb0 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a   disallow the.**
20bc0 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e   specific action
20bd0 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53   but allow the S
20be0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
20bf0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a  continue to be.*
20c00 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b  * compiled, or [
20c10 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20  SQLITE_DENY] to 
20c20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72 65  cause the entire
20c30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
20c40 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64  o be.** rejected
20c50 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20   with an error. 
20c60 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69   ^If the authori
20c70 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  zer callback ret
20c80 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75  urns.** any valu
20c90 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
20ca0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53  LITE_IGNORE], [S
20cb0 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53  QLITE_OK], or [S
20cc0 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74  QLITE_DENY].** t
20cd0 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hen the [sqlite3
20ce0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
20cf0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
20d00 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
20d10 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
20d20 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
20d30 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
20d40 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  ge..**.** When t
20d50 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
20d60 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
20d70 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20   that means the 
20d80 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71  operation.** req
20d90 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e  uested is ok.  ^
20da0 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
20db0 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
20dc0 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20  E_DENY], the.** 
20dd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
20de0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
20df0 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
20e00 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20  riggered the.** 
20e10 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
20e20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
20e30 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61  or message expla
20e40 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63  ining that.** ac
20e50 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20  cess is denied. 
20e60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
20e70 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  t parameter to t
20e80 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20e90 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
20ea0 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   of the third.**
20eb0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
20ec0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
20ed0 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72  thorizer() inter
20ee0 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e  face. ^The secon
20ef0 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
20f00 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
20f10 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51  s an integer [SQ
20f20 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69  LITE_COPY | acti
20f30 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70  on code] that sp
20f40 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70  ecifies.** the p
20f50 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e  articular action
20f60 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65   to be authorize
20f70 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74 68  d. ^The third th
20f80 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72 61  rough sixth para
20f90 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65  meters.** to the
20fa0 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65   callback are ze
20fb0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
20fc0 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61  rings that conta
20fd0 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  in additional.**
20fe0 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74   details about t
20ff0 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  he action to be 
21000 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a  authorized..**.*
21010 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e  * ^If the action
21020 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45   code is [SQLITE
21030 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68  _READ].** and th
21040 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
21050 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ns [SQLITE_IGNOR
21060 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  E] then the.** [
21070 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21080 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  nt] statement is
21090 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20   constructed to 
210a0 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20  substitute.** a 
210b0 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c  NULL value in pl
210c0 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65  ace of the table
210d0 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75   column that wou
210e0 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20  ld have.** been 
210f0 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f  read if [SQLITE_
21100 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74  OK] had been ret
21110 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c  urned.  The [SQL
21120 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72  ITE_IGNORE].** r
21130 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65  eturn can be use
21140 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74  d to deny an unt
21150 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63 65  rusted user acce
21160 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c  ss to individual
21170 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61  .** columns of a
21180 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74   table..** ^If t
21190 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
211a0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  s [SQLITE_DELETE
211b0 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  ] and the callba
211c0 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53  ck returns.** [S
211d0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
211e0 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20  en the [DELETE] 
211f0 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65  operation procee
21200 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74  ds but the.** [t
21210 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61  runcate optimiza
21220 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65  tion] is disable
21230 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61  d and all rows a
21240 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76  re deleted indiv
21250 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41  idually..**.** A
21260 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  n authorizer is 
21270 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74  used when [sqlit
21280 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
21290 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73  paring].** SQL s
212a0 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61  tatements from a
212b0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  n untrusted sour
212c0 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68  ce, to ensure th
212d0 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  at the SQL state
212e0 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20  ments.** do not 
212f0 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64 61  try to access da
21300 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20  ta they are not 
21310 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20  allowed to see, 
21320 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f 20  or that they do 
21330 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78  not.** try to ex
21340 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20  ecute malicious 
21350 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
21360 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61 62  damage the datab
21370 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61  ase.  For.** exa
21380 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
21390 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61  tion may allow a
213a0 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61   user to enter a
213b0 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20  rbitrary.** SQL 
213c0 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c  queries for eval
213d0 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61  uation by a data
213e0 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20 61  base.  But the a
213f0 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a  pplication does.
21400 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20  ** not want the 
21410 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20  user to be able 
21420 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72  to make arbitrar
21430 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  y changes to the
21440 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41  .** database.  A
21450 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75  n authorizer cou
21460 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20 69  ld then be put i
21470 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68  n place while th
21480 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65  e.** user-entere
21490 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b  d SQL is being [
214a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20  sqlite3_prepare 
214b0 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61 74  | prepared] that
214c0 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76  .** disallows ev
214d0 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74 20  erything except 
214e0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
214f0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69  nts..**.** Appli
21500 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65  cations that nee
21510 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c  d to process SQL
21520 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20   from untrusted 
21530 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74  sources.** might
21540 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c   also consider l
21550 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65  owering resource
21560 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73   limits using [s
21570 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a  qlite3_limit()].
21580 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20  ** and limiting 
21590 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75 73  database size us
215a0 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67  ing the [max_pag
215b0 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
215c0 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e  ].** in addition
215d0 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74   to using an aut
215e0 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  horizer..**.** ^
215f0 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61  (Only a single a
21600 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65  uthorizer can be
21610 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64   in place on a d
21620 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
21630 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e  on.** at a time.
21640 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73    Each call to s
21650 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
21660 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20  rizer overrides 
21670 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20  the.** previous 
21680 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c  call.)^  ^Disabl
21690 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  e the authorizer
216a0 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61   by installing a
216b0 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a   NULL callback..
216c0 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65  ** The authorize
216d0 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  r is disabled by
216e0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
216f0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
21700 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
21710 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
21720 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
21730 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
21740 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
21750 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72  voked the author
21760 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  izer callback..*
21770 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
21780 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
21790 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
217a0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
217b0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
217c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
217d0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
217e0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
217f0 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
21800 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71  .**.** ^When [sq
21810 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21820 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70  ()] is used to p
21830 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
21840 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65  nt, the.** state
21850 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65  ment might be re
21860 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e 67  -prepared during
21870 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
21880 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73  ] due to a .** s
21890 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48  chema change.  H
218a0 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63  ence, the applic
218b0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73  ation should ens
218c0 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ure that the.** 
218d0 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a  correct authoriz
218e0 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61  er callback rema
218f0 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72  ins in place dur
21900 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
21910 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _step()]..**.** 
21920 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 61  ^Note that the a
21930 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
21940 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  ck is invoked on
21950 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71  ly during.** [sq
21960 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
21970 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
21980 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  .  Authorization
21990 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f   is not.** perfo
219a0 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61 74  rmed during stat
219b0 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ement evaluation
219c0 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   in [sqlite3_ste
219d0 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20  p()], unless.** 
219e0 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68 65  as stated in the
219f0 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
21a00 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  aph, sqlite3_ste
21a10 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73  p() invokes.** s
21a20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21a30 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72 65  2() to reprepare
21a40 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74   a statement aft
21a50 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  er a schema chan
21a60 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ge..*/.SQLITE_AP
21a70 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
21a80 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73 65 74  CALL sqlite3_set
21a90 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
21aa0 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
21ab0 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
21ac0 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
21ad0 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
21ae0 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
21af0 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
21b00 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
21b10 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
21b20 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
21b30 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
21b40 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21b50 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
21b60 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
21b70 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
21b80 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
21b90 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
21ba0 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
21bb0 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
21bc0 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
21bd0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
21be0 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
21bf0 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
21c00 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
21c10 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
21c20 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
21c30 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
21c40 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
21c50 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
21c60 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
21c70 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
21c80 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63  ed as a [conflic
21c90 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64  t resolution mod
21ca0 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66  e].** returned f
21cb0 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
21cc0 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
21cd0 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
21ce0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21cf0 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
21d00 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
21d10 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
21d20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
21d30 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
21d40 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
21d50 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
21d60 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
21d70 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
21d80 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
21d90 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
21da0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
21db0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21dc0 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
21dd0 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
21de0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
21df0 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
21e00 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
21e10 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
21e20 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
21e30 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
21e40 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
21e50 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
21e60 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
21e70 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
21e80 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
21e90 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
21ea0 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
21eb0 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
21ec0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
21ed0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21ee0 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
21ef0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
21f00 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
21f10 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
21f20 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
21f30 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
21f40 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
21f50 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
21f60 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
21f70 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
21f80 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
21f90 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
21fa0 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
21fb0 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
21fc0 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
21fd0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
21fe0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
21ff0 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
22000 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
22010 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
22020 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
22030 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
22040 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
22050 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
22060 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
22070 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
22080 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
22090 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
220a0 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
220b0 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
220c0 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
220d0 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
220e0 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
220f0 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
22100 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
22110 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
22120 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
22130 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
22140 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22150 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22160 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
22170 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
22180 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
22190 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
221a0 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
221b0 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
221c0 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
221d0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
221e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
221f0 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
22200 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
22210 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
22220 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22230 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22240 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
22250 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
22260 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
22270 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
22280 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22290 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
222a0 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
222b0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
222c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
222d0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
222e0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
222f0 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
22300 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
22310 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22320 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
22330 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
22340 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
22350 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22360 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22370 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
22380 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
22390 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
223a0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
223b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
223c0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
223d0 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
223e0 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
223f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22400 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22410 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
22420 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
22430 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22440 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22450 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22460 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
22470 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
22480 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
22490 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
224a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
224b0 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
224c0 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
224d0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
224e0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
224f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22500 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
22510 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
22520 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
22530 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22540 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22550 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
22560 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
22570 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
22580 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22590 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
225a0 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
225b0 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
225c0 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
225d0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
225e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
225f0 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
22600 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
22610 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
22620 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22640 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
22650 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
22660 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
22670 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22690 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
226a0 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
226b0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
226c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
226d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
226e0 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
226f0 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
22700 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
22710 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
22720 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
22730 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
22740 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
22750 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
22760 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
22770 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
22780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
22790 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
227a0 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
227b0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
227c0 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
227d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
227e0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
227f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22800 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22810 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
22820 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
22830 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
22840 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22850 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22860 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
22870 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
22880 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
22890 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
228a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
228b0 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
228c0 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
228d0 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
228e0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
228f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22900 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
22910 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
22920 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
22930 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22940 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22950 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
22960 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
22970 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
22980 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22990 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
229a0 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
229b0 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
229c0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
229d0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
229e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
229f0 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
22a00 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
22a10 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
22a20 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
22a30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22a40 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
22a50 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
22a60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
22a70 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
22a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22a90 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
22aa0 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
22ab0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
22ac0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
22ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
22ae0 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
22af0 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
22b00 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
22b10 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
22b20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
22b30 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
22b40 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
22b50 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
22b60 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
22b70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
22b80 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
22b90 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
22ba0 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
22bb0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
22bc0 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
22bd0 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
22be0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
22bf0 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
22c00 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
22c10 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
22c20 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d  g Functions.** M
22c30 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a  ETHOD: sqlite3.*
22c40 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
22c50 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
22c60 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
22c70 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
22c80 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
22c90 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
22ca0 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
22cb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
22cc0 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
22cd0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
22ce0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
22cf0 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
22d00 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
22d10 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
22d20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
22d30 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
22d40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
22d50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
22d60 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
22d70 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
22d80 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
22d90 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
22da0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
22db0 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
22dc0 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
22dd0 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
22de0 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
22df0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
22e00 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
22e10 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
22e20 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
22e30 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
22e40 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
22e50 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
22e60 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
22e70 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
22e80 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
22e90 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er.)^.**.** The 
22ea0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
22eb0 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
22ec0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61  e-time option ca
22ed0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d  n be used to lim
22ee0 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68  it.** the length
22ef0 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
22f00 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20  eter] expansion 
22f10 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  in the output of
22f20 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
22f30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
22f40 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
22f50 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
22f60 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
22f70 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
22f80 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
22f90 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
22fa0 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
22fb0 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
22fc0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
22fd0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
22fe0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
22ff0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
23000 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
23010 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
23020 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
23030 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
23040 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
23050 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
23060 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
23070 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
23080 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
23090 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
230a0 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
230b0 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
230c0 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
230d0 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
230e0 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
230f0 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
23100 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
23110 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
23120 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
23130 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
23140 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
23150 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
23160 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
23170 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
23180 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
23190 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
231a0 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
231b0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
231c0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
231d0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51  ITE_API void *SQ
231e0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
231f0 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
23200 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
23210 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
23220 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
23230 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
23240 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
23250 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41  id *SQLITE_STDCA
23260 4c 4c 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  LL sqlite3_profi
23270 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20  le(sqlite3*,.   
23280 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28  void(*xProfile)(
23290 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72  void*,const char
232a0 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  *,sqlite3_uint64
232b0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
232c0 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72  * CAPI3REF: Quer
232d0 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62  y Progress Callb
232e0 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  acks.** METHOD: 
232f0 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
23300 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
23310 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
23320 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
23330 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
23340 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
23350 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
23360 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
23370 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
23380 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
23390 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
233a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
233b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
233c0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
233d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
233e0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
233f0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
23400 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
23410 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
23420 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
23430 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
23440 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
23450 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
23460 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
23470 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
23480 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
23490 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
234a0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
234b0 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20  the approximate 
234c0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
234d0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
234e0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
234f0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
23500 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
23510 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
23520 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
23530 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c  k X.  ^If N is l
23540 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65  ess than one the
23550 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a  n the progress.*
23560 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73  * handler is dis
23570 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e  abled..**.** ^On
23580 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67  ly a single prog
23590 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79  ress handler may
235a0 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f   be defined at o
235b0 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b  ne time per.** [
235c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
235d0 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20  ion]; setting a 
235e0 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e  new progress han
235f0 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65  dler cancels the
23600 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53  .** old one.  ^S
23610 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72  etting parameter
23620 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62   X to NULL disab
23630 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73 73  les the progress
23640 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68   handler..** ^Th
23650 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
23660 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62  er is also disab
23670 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e  led by setting N
23680 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73   to a value less
23690 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a  .** than 1..**.*
236a0 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65  * ^If the progre
236b0 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  ss callback retu
236c0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
236d0 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a  e operation is.*
236e0 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20  * interrupted.  
236f0 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61 6e  This feature can
23700 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c   be used to impl
23710 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63  ement a.** "Canc
23720 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20  el" button on a 
23730 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69 61  GUI progress dia
23740 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54  log box..**.** T
23750 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
23760 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73  ler callback mus
23770 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
23780 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
23790 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
237a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
237b0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70  at invoked the p
237c0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
237d0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
237e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
237f0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
23800 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
23810 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
23820 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23830 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
23840 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
23850 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
23860 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f  h..**.*/.SQLITE_
23870 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45 5f  API void SQLITE_
23880 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
23890 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
238a0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20  (sqlite3*, int, 
238b0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76  int(*)(void*), v
238c0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
238d0 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20  PI3REF: Opening 
238e0 41 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43  A New Database C
238f0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 43 4f 4e  onnection.** CON
23900 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74 65  STRUCTOR: sqlite
23910 33 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  3.**.** ^These r
23920 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20  outines open an 
23930 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20  SQLite database 
23940 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65  file as specifie
23950 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c  d by the .** fil
23960 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20  ename argument. 
23970 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72  ^The filename ar
23980 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70  gument is interp
23990 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66  reted as UTF-8 f
239a0 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
239b0 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
239c0 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61  _open_v2() and a
239d0 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  s UTF-16 in the 
239e0 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f  native byte.** o
239f0 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
23a00 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b  _open16(). ^(A [
23a10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23a20 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75  ion] handle is u
23a30 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e  sually.** return
23a40 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65  ed in *ppDb, eve
23a50 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63  n if an error oc
23a60 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20  curs.  The only 
23a70 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61  exception is tha
23a80 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69  t.** if SQLite i
23a90 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
23aa0 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68  cate memory to h
23ab0 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  old the [sqlite3
23ac0 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e  ] object,.** a N
23ad0 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74  ULL will be writ
23ae0 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69  ten into *ppDb i
23af0 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e  nstead of a poin
23b00 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
23b10 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29  te3].** object.)
23b20 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62  ^ ^(If the datab
23b30 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61  ase is opened (a
23b40 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73  nd/or created) s
23b50 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65  uccessfully, the
23b60 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  n.** [SQLITE_OK]
23b70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f   is returned.  O
23b80 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
23b90 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
23ba0 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20  rned.)^ ^The.** 
23bb0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
23bc0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65  )] or [sqlite3_e
23bd0 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69  rrmsg16()] routi
23be0 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20  nes can be used 
23bf0 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20  to obtain.** an 
23c00 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65  English language
23c10 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20   description of 
23c20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77  the error follow
23c30 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66  ing a failure of
23c40 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73   any.** of the s
23c50 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f  qlite3_open() ro
23c60 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  utines..**.** ^T
23c70 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64  he default encod
23c80 69 6e 67 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ing will be UTF-
23c90 38 20 66 6f 72 20 64 61 74 61 62 61 73 65 73 20  8 for databases 
23ca0 63 72 65 61 74 65 64 20 75 73 69 6e 67 0a 2a 2a  created using.**
23cb0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
23cc0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
23cd0 76 32 28 29 2e 20 20 5e 54 68 65 20 64 65 66 61  v2().  ^The defa
23ce0 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72  ult encoding for
23cf0 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 63 72   databases.** cr
23d00 65 61 74 65 64 20 75 73 69 6e 67 20 73 71 6c 69  eated using sqli
23d10 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 77 69 6c  te3_open16() wil
23d20 6c 20 62 65 20 55 54 46 2d 31 36 20 69 6e 20 74  l be UTF-16 in t
23d30 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
23d40 72 64 65 72 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  rder..**.** Whet
23d50 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
23d60 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
23d70 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
23d80 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
23d90 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
23da0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23db0 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
23dc0 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
23dd0 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
23de0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
23df0 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
23e00 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
23e10 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
23e20 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
23e30 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
23e40 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
23e50 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
23e60 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
23e70 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
23e80 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
23e90 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
23ea0 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
23eb0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23ec0 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
23ed0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
23ee0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23ef0 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
23f00 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
23f10 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
23f20 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
23f30 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
23f40 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
23f50 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
23f60 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
23f70 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
23f80 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
23f90 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
23fa0 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
23fb0 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
23fc0 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
23fd0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
23fe0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
23ff0 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
24000 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
24010 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
24020 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
24030 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
24040 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
24050 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
24060 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
24070 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
24080 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
24090 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
240a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
240b0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
240c0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
240d0 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
240e0 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
240f0 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
24100 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
24110 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
24120 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
24130 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
24140 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
24150 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
24160 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
24170 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
24180 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
24190 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
241a0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
241b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
241c0 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
241d0 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
241e0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
241f0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
24200 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
24210 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
24220 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
24230 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
24240 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
24250 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
24260 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
24270 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
24280 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
24290 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
242a0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
242b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
242c0 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
242d0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
242e0 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
242f0 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
24300 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
24310 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
24320 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
24330 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
24340 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
24350 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
24360 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
24370 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
24380 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
24390 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
243a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
243b0 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
243c0 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
243d0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
243e0 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
243f0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
24400 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
24410 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
24420 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
24430 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
24440 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
24450 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
24460 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
24470 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24480 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
24490 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
244a0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
244b0 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
244c0 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
244d0 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
244e0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
244f0 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
24500 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
24510 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
24520 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
24530 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24540 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
24550 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
24560 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
24570 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
24580 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
24590 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
245a0 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
245b0 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
245c0 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
245d0 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
245e0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
245f0 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
24600 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
24610 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
24620 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
24630 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
24640 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
24650 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
24660 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
24670 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
24680 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
24690 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
246a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
246b0 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
246c0 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
246d0 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
246e0 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
246f0 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
24700 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
24710 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
24720 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
24730 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
24740 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
24750 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
24760 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
24770 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
24780 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
24790 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
247a0 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
247b0 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
247c0 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
247d0 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
247e0 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
247f0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
24800 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
24810 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
24820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
24830 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
24840 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
24850 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
24860 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
24870 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
24880 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
24890 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
248a0 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
248b0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
248c0 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
248d0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
248e0 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
248f0 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
24900 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
24910 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
24920 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
24930 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
24940 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
24950 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
24960 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
24970 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
24980 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
24990 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
249a0 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
249b0 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
249c0 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
249d0 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
249e0 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
249f0 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
24a00 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
24a10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24a20 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
24a30 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
24a40 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
24a50 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
24a60 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
24a70 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
24a80 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
24a90 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
24aa0 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
24ab0 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
24ac0 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
24ad0 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
24ae0 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
24af0 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
24b00 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
24b10 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
24b20 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
24b30 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
24b40 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
24b50 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
24b60 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
24b70 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
24b80 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
24b90 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
24ba0 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
24bb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
24bc0 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
24bd0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
24be0 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
24bf0 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
24c00 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
24c10 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
24c20 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
24c30 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
24c40 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
24c50 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
24c60 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
24c70 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
24c80 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
24c90 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
24ca0 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
24cb0 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
24cc0 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
24cd0 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
24ce0 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
24cf0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
24d00 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
24d10 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
24d20 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
24d30 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
24d40 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
24d50 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
24d60 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
24d70 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
24d80 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
24d90 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
24da0 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
24db0 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
24dc0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
24dd0 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
24de0 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
24df0 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
24e00 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
24e10 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
24e20 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
24e30 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
24e40 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
24e50 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
24e60 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
24e70 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
24e80 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
24e90 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
24ea0 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
24eb0 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
24ec0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
24ed0 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
24ee0 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
24ef0 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
24f00 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
24f10 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
24f20 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
24f30 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
24f40 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
24f50 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
24f60 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
24f70 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
24f80 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
24f90 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
24fa0 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 28 4f  ve path. .** ^(O
24fb0 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66  n windows, the f
24fc0 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  irst component o
24fd0 66 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  f an absolute pa
24fe0 74 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76  th .** is a driv
24ff0 65 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20  e specification 
25000 28 65 2e 67 2e 20 22 43 3a 22 29 2e 29 5e 0a 2a  (e.g. "C:").)^.*
25010 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20  *.** [[core URI 
25020 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
25030 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79 20  ]].** The query 
25040 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
25050 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70  RI may contain p
25060 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20 61  arameters that a
25070 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a 2a  re interpreted.*
25080 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c 69  * either by SQLi
25090 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62 79  te itself, or by
250a0 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d   a [VFS | custom
250b0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
250c0 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20  ion]..** SQLite 
250d0 61 6e 64 20 69 74 73 20 62 75 69 6c 74 2d 69 6e  and its built-in
250e0 20 5b 56 46 53 65 73 5d 20 69 6e 74 65 72 70 72   [VFSes] interpr
250f0 65 74 20 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77  et the.** follow
25100 69 6e 67 20 71 75 65 72 79 20 70 61 72 61 6d 65  ing query parame
25110 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ters:.**.** <ul>
25120 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66  .**   <li> <b>vf
25130 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73  s</b>: ^The "vfs
25140 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  " parameter may 
25150 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69  be used to speci
25160 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a  fy the name of.*
25170 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65  *     a VFS obje
25180 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73  ct that provides
25190 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
251a0 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
251b0 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20  that should.**  
251c0 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63     be used to ac
251d0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
251e0 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20  e file on disk. 
251f0 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ^If this option 
25200 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20  is set to.**    
25210 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
25220 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53   the default VFS
25230 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e   object is used.
25240 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
25250 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56  unknown.**     V
25260 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20  FS is an error. 
25270 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
25280 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
25290 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e  d the vfs option
252a0 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65   is.**     prese
252b0 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53  nt, then the VFS
252c0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
252d0 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70  e option takes p
252e0 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a  recedence over.*
252f0 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20  *     the value 
25300 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f  passed as the fo
25310 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
25320 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
25330 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
25340 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e  > <b>mode</b>: ^
25350 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65  (The mode parame
25360 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
25370 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22  o either "ro", "
25380 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63  rw",.**     "rwc
25390 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20  ", or "memory". 
253a0 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65  Attempting to se
253b0 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65  t it to any othe
253c0 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20  r value is.**   
253d0 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a    an error)^. .*
253e0 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69  *     ^If "ro" i
253f0 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65  s specified, the
25400 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  n the database i
25410 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
25420 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61  d-only .**     a
25430 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69  ccess, just as i
25440 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
25450 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61  EN_READONLY] fla
25460 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69  g had been set i
25470 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68  n the .**     th
25480 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ird argument to 
25490 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
254a0 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
254b0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
254c0 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
254d0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
254e0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
254f0 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
25500 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
25510 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
25520 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
25530 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
25540 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
25550 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
25560 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
25570 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
25580 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
25590 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
255a0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
255b0 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
255c0 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20  EN_CREATE.  ^If 
255d0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
255e0 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f  is.**     set to
255f0 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61   "memory" then a
25600 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79   pure [in-memory
25610 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20   database] that 
25620 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20  never reads.**  
25630 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f     or writes fro
25640 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20  m disk is used. 
25650 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20  ^It is an error 
25660 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
25670 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68  ue for.**     th
25680 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72  e mode parameter
25690 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65   that is less re
256a0 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74  strictive than t
256b0 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79  hat specified by
256c0 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67  .**     the flag
256d0 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20  s passed in the 
256e0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
256f0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
25700 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
25710 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a  i> <b>cache</b>:
25720 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61   ^The cache para
25730 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
25740 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72   to either "shar
25750 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70  ed" or.**     "p
25760 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e  rivate". ^Settin
25770 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22  g it to "shared"
25780 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74   is equivalent t
25790 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a  o setting the.**
257a0 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
257b0 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74  _SHAREDCACHE bit
257c0 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72   in the flags ar
257d0 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f  gument passed to
257e0 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f  .**     sqlite3_
257f0 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74  open_v2(). ^Sett
25800 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61  ing the cache pa
25810 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76  rameter to "priv
25820 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20  ate" is .**     
25830 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
25840 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45  tting the SQLITE
25850 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
25860 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e  HE bit..**     ^
25870 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
25880 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
25890 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72   the "cache" par
258a0 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e  ameter is presen
258b0 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52  t in.**     a UR
258c0 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20  I filename, its 
258d0 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20  value overrides 
258e0 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71  any behavior req
258f0 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
25900 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
25910 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
25920 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
25930 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
25940 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c  g..**.**  <li> <
25950 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65  b>psow</b>: ^The
25960 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20   psow parameter 
25970 69 6e 64 69 63 61 74 65 73 20 77 68 65 74 68 65  indicates whethe
25980 72 20 6f 72 20 6e 6f 74 20 74 68 65 0a 2a 2a 20  r or not the.** 
25990 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f      [powersafe o
259a0 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72  verwrite] proper
259b0 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20  ty does or does 
259c0 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65  not apply to the
259d0 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20  .**     storage 
259e0 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74  media on which t
259f0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
25a00 20 72 65 73 69 64 65 73 2e 0a 2a 2a 0a 2a 2a 20   resides..**.** 
25a10 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b 3c   <li> <b>nolock<
25a20 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63 6b  /b>: ^The nolock
25a30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
25a40 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70 61  boolean query pa
25a50 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20 77  rameter.**     w
25a60 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73 61  hich if set disa
25a70 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69 6e  bles file lockin
25a80 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a 6f  g in rollback jo
25a90 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54 68  urnal modes.  Th
25aa0 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73 65  is.**     is use
25ab0 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69 6e  ful for accessin
25ac0 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e 20  g a database on 
25ad0 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68 61  a filesystem tha
25ae0 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20 20  t does not.**   
25af0 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69 6e    support lockin
25b00 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44 61  g.  Caution:  Da
25b10 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
25b20 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  n might result i
25b30 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72 20  f two.**     or 
25b40 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20 77  more processes w
25b50 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d 65  rite to the same
25b60 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6e   database and an
25b70 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a 2a  y one of those.*
25b80 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73 20  *     processes 
25b90 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a 2a  uses nolock=1..*
25ba0 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69 6d  *.**  <li> <b>im
25bb0 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54 68  mutable</b>: ^Th
25bc0 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72 61  e immutable para
25bd0 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c 65  meter is a boole
25be0 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20  an query.**     
25bf0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
25c00 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
25c10 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
25c20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a 20  is stored on.** 
25c30 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65      read-only me
25c40 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d 75  dia.  ^When immu
25c50 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53 51  table is set, SQ
25c60 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
25c70 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74  t the.**     dat
25c80 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e 6f  abase file canno
25c90 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65 76  t be changed, ev
25ca0 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73 20  en by a process 
25cb0 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20 20  with higher.**  
25cc0 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61 6e     privilege, an
25cd0 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61 73  d so the databas
25ce0 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61 64  e is opened read
25cf0 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c 6f  -only and all lo
25d00 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e 64  cking.**     and
25d10 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69 6f   change detectio
25d20 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20 20  n is disabled.  
25d30 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e 67  Caution: Setting
25d40 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a 2a   the immutable.*
25d50 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20 6f  *     property o
25d60 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
25d70 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20 66  e that does in f
25d80 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20 72  act change can r
25d90 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e 20  esult.**     in 
25da0 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79 20  incorrect query 
25db0 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20 5b  results and/or [
25dc0 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 20  SQLITE_CORRUPT] 
25dd0 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20 53  errors..**     S
25de0 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
25df0 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45  _IOCAP_IMMUTABLE
25e00 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a 20  ]..**       .** 
25e10 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65  </ul>.**.** ^Spe
25e20 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f  cifying an unkno
25e30 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  wn parameter in 
25e40 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e  the query compon
25e50 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73 20  ent of a URI is 
25e60 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e  not an.** error.
25e70 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
25e80 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
25e90 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64  t understand add
25ea0 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a  itional query.**
25eb0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65   parameters.  Se
25ec0 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65  e "[query parame
25ed0 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69 61  ters with specia
25ee0 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c  l meaning to SQL
25ef0 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64  ite]" for.** add
25f00 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
25f10 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  ion..**.** [[URI
25f20 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
25f30 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c  es]] <h3>URI fil
25f40 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f  ename examples</
25f50 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65  h3>.**.** <table
25f60 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67   border="1" alig
25f70 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64  n=center cellpad
25f80 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c  ding=5>.** <tr><
25f90 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  th> URI filename
25fa0 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a  s <th> Results.*
25fb0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
25fc0 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a  data.db <td> .**
25fd0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
25fe0 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
25ff0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
26000 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c   directory..** <
26010 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
26020 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c  me/fred/data.db<
26030 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  br>.**          
26040 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65  file:///home/fre
26050 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a  d/data.db <br> .
26060 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
26070 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d  ://localhost/hom
26080 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
26090 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  br> <td> .**    
260a0 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64        Open the d
260b0 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68  atabase file "/h
260c0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
260d0 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
260e0 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68  ile://darkstar/h
260f0 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
26100 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
26110 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61     An error. "da
26120 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61  rkstar" is not a
26130 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68   recognized auth
26140 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  ority..** <tr><t
26150 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73  d style="white-s
26160 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a  pace:nowrap"> .*
26170 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
26180 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25  ///C:/Documents%
26190 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73  20and%20Settings
261a0 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61  /fred/Desktop/da
261b0 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64  ta.db.**     <td
261c0 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20  > Windows only: 
261d0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
261e0 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27  ata.db" on fred'
261f0 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69  s desktop on dri
26200 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43  ve.**          C
26210 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  :. Note that the
26220 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e   %20 escaping in
26230 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73   this example is
26240 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a   not strictly .*
26250 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73  *          neces
26260 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61  sary - space cha
26270 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75  racters can be u
26280 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a  sed literally.**
26290 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49            in URI
262a0 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c   filenames..** <
262b0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74  tr><td> file:dat
262c0 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63  a.db?mode=ro&cac
262d0 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20  he=private <td> 
262e0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
262f0 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  n file "data.db"
26300 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
26310 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65  directory for re
26320 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a  ad-only access..
26330 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61  **          Rega
26340 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
26350 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d  r or not shared-
26360 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e  cache mode is en
26370 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  abled by.**     
26380 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73       default, us
26390 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68  e a private cach
263a0 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  e..** <tr><td> f
263b0 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  ile:/home/fred/d
263c0 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d  ata.db?vfs=unix-
263d0 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a 20  dotfile <td>.** 
263e0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69           Open fi
263f0 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
26400 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65  ata.db". Use the
26410 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e   special VFS "un
26420 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20 20  ix-dotfile".**  
26430 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73 65          that use
26440 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20 70  s dot-files in p
26450 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61 64  lace of posix ad
26460 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e 0a  visory locking..
26470 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
26480 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65  :data.db?mode=re
26490 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20  adonly <td> .** 
264a0 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
264b0 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73  r. "readonly" is
264c0 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74   not a valid opt
264d0 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64  ion for the "mod
264e0 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  e" parameter..**
264f0 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20   </table>.**.** 
26500 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c  ^URI hexadecimal
26510 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65   escape sequence
26520 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70  s (%HH) are supp
26530 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65  orted within the
26540 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65   path and.** que
26550 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
26560 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65   a URI. A hexade
26570 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
26580 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f  uence consists o
26590 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73  f a.** percent s
265a0 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c  ign - "%" - foll
265b0 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20  owed by exactly 
265c0 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20  two hexadecimal 
265d0 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69  digits .** speci
265e0 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76  fying an octet v
265f0 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68  alue. ^Before th
26600 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20  e path or query 
26610 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a  components of a.
26620 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  ** URI filename 
26630 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c  are interpreted,
26640 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65   they are encode
26650 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e  d using UTF-8 an
26660 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65  d all .** hexade
26670 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
26680 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20  uences replaced 
26690 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65  by a single byte
266a0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a   containing the.
266b0 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ** corresponding
266c0 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20   octet. If this 
266d0 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65  process generate
266e0 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46  s an invalid UTF
266f0 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20  -8 encoding,.** 
26700 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
26710 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
26720 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
26730 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ows users:</b>  
26740 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  The encoding use
26750 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61  d for the filena
26760 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f  me argument.** o
26770 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  f sqlite3_open()
26780 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
26790 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55  n_v2() must be U
267a0 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76  TF-8, not whatev
267b0 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69  er.** codepage i
267c0 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  s currently defi
267d0 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20  ned.  Filenames 
267e0 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72  containing inter
267f0 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72  national.** char
26800 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63  acters must be c
26810 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d  onverted to UTF-
26820 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69  8 prior to passi
26830 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20  ng them into.** 
26840 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
26850 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
26860 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  2()..**.** <b>No
26870 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75  te to Windows Ru
26880 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e  ntime users:</b>
26890 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20    The temporary 
268a0 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62  directory must b
268b0 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74  e set.** prior t
268c0 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65  o calling sqlite
268d0 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
268e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20  te3_open_v2().  
268f0 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f  Otherwise, vario
26900 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74  us.** features t
26910 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65 20  hat require the 
26920 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79  use of temporary
26930 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e   files may fail.
26940 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
26950 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64   [sqlite3_temp_d
26960 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c  irectory].*/.SQL
26970 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
26980 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
26990 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74  e3_open(.  const
269a0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
269b0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
269c0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
269d0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
269e0 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb          /* 
269f0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
26a00 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49  andle */.);.SQLI
26a10 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
26a20 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
26a30 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
26a40 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
26a50 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
26a60 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
26a70 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
26a80 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
26a90 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
26aa0 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
26ab0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
26ac0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
26ad0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63  te3_open_v2(.  c
26ae0 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
26af0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
26b00 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
26b10 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
26b20 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20 20   **ppDb,        
26b30 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
26b40 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69  db handle */.  i
26b50 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20 20  nt flags,       
26b60 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73 20         /* Flags 
26b70 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
26b80 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a 20  *zVfs        /* 
26b90 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64 75  Name of VFS modu
26ba0 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a  le to use */.);.
26bb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
26bc0 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20 46   Obtain Values F
26bd0 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65 72  or URI Parameter
26be0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72  s.**.** These ar
26bf0 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69 6e  e utility routin
26c00 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56 46  es, useful to VF
26c10 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
26c20 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a  s, that check.**
26c30 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61 74   to see if a dat
26c40 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20 61  abase file was a
26c50 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61 69   URI that contai
26c60 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20 71  ned a specific q
26c70 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74  uery .** paramet
26c80 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f 62  er, and if so ob
26c90 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65 20  tains the value 
26ca0 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70 61  of that query pa
26cb0 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
26cc0 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61 62  f F is the datab
26cd0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69  ase filename poi
26ce0 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74 6f  nter passed into
26cf0 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65 74   the xOpen() met
26d00 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53  hod of .** a VFS
26d10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
26d20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20 70  when the flags p
26d30 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
26d40 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a  n() has one or .
26d50 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b  ** more of the [
26d60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
26d70 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e   or [SQLITE_OPEN
26d80 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20 73  _MAIN_DB] bits s
26d90 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74  et and.** P is t
26da0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 71  he name of the q
26db0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c 20  uery parameter, 
26dc0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
26dd0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
26de0 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 76  P) returns the v
26df0 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a  alue of the P.**
26e00 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69 74   parameter if it
26e10 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55 4c   exists or a NUL
26e20 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20 64  L pointer if P d
26e30 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20 61  oes not appear a
26e40 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70 61  s a .** query pa
26e50 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20 49  rameter on F.  I
26e60 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20 70  f P is a query p
26e70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a  arameter of F.**
26e80 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69 74   has no explicit
26e90 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c   value, then sql
26ea0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
26eb0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 0a  er(F,P) returns.
26ec0 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
26ed0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2e  an empty string.
26ee0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
26ef0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
26f00 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61 73  ,P,B) routine as
26f10 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73 20  sumes that P is 
26f20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72  a boolean.** par
26f30 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
26f40 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20 66  ns true (1) or f
26f50 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64 69  alse (0) accordi
26f60 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65 0a  ng to the value.
26f70 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73 71  ** of P.  The sq
26f80 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
26f90 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
26fa0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
26fb0 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ) if the.** valu
26fc0 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61 6d  e of query param
26fd0 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
26fe0 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c 20   "yes", "true", 
26ff0 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a  or "on" in any.*
27000 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68 65  * case or if the
27010 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
27020 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75  th a non-zero nu
27030 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73  mber.  The .** s
27040 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
27050 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
27060 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65  es returns false
27070 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c 75   (0) if the valu
27080 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70 61  e of.** query pa
27090 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
270a0 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65   of "no", "false
270b0 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20 61  ", or "off" in a
270c0 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66  ny case or.** if
270d0 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
270e0 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69 63  s with a numeric
270f0 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73 20   zero.  If P is 
27100 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20 70  not a query.** p
27110 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72  arameter on F or
27120 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
27130 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d   P is does not m
27140 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65 0a  atch any of the.
27150 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20 73  ** above, then s
27160 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
27170 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
27180 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20  s (B!=0)..**.** 
27190 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
271a0 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f 75  int64(F,P,D) rou
271b0 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74 68  tine converts th
271c0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e 74  e value of P int
271d0 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69  o a.** 64-bit si
271e0 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e 64  gned integer and
271f0 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69 6e   returns that in
27200 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20 50  teger, or D if P
27210 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69   does not.** exi
27220 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c 75  st.  If the valu
27230 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74 68  e of P is someth
27240 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 61  ing other than a
27250 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a  n integer, then.
27260 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  ** zero is retur
27270 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46  ned..** .** If F
27280 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
27290 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  er, then sqlite3
272a0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
272b0 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  ,P) returns NULL
272c0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
272d0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
272e0 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20 49  B) returns B.  I
272f0 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c  f F is not a NUL
27300 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a  L pointer and.**
27310 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
27320 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  se file pathname
27330 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53 51   pointer that SQ
27340 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74 6f  Lite passed into
27350 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46   the xOpen.** VF
27360 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74  S method, then t
27370 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
27380 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
27390 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
273a0 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72  bably.** undesir
273b0 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  able..*/.SQLITE_
273c0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
273d0 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
273e0 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
273f0 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
27400 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
27410 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
27420 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
27430 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
27440 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
27450 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  an(const char *z
27460 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72  File, const char
27470 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44   *zParam, int bD
27480 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f  efault);.SQLITE_
27490 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
274a0 34 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  4 SQLITE_STDCALL
274b0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
274c0 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  64(const char*, 
274d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
274e0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f  ite3_int64);.../
274f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
27500 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
27510 65 73 73 61 67 65 73 0a 2a 2a 20 4d 45 54 48 4f  essages.** METHO
27520 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
27530 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
27540 63 65 6e 74 20 73 71 6c 69 74 65 33 5f 2a 20 41  cent sqlite3_* A
27550 50 49 20 63 61 6c 6c 20 61 73 73 6f 63 69 61 74  PI call associat
27560 65 64 20 77 69 74 68 20 0a 2a 2a 20 5b 64 61 74  ed with .** [dat
27570 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
27580 5d 20 44 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  ] D failed, then
27590 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72   the sqlite3_err
275a0 63 6f 64 65 28 44 29 20 69 6e 74 65 72 66 61 63  code(D) interfac
275b0 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 74 68 65  e.** returns the
275c0 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74   numeric [result
275d0 20 63 6f 64 65 5d 20 6f 72 20 5b 65 78 74 65 6e   code] or [exten
275e0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
275f0 20 66 6f 72 20 74 68 61 74 0a 2a 2a 20 41 50 49   for that.** API
27600 20 63 61 6c 6c 2e 0a 2a 2a 20 49 66 20 74 68 65   call..** If the
27610 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50 49   most recent API
27620 20 63 61 6c 6c 20 77 61 73 20 73 75 63 63 65 73   call was succes
27630 73 66 75 6c 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  sful,.** then th
27640 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
27650 72 6f 6d 20 73 71 6c 69 74 65 33 5f 65 72 72 63  rom sqlite3_errc
27660 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
27670 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ed..** ^The sqli
27680 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
27690 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
276a0 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
276b0 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
276c0 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
276d0 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
276e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
276f0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
27700 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
27710 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
27720 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27730 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
27740 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
27750 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
27760 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
27770 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
27780 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
27790 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
277a0 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
277b0 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
277c0 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
277d0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
277e0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
277f0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
27800 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
27810 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
27820 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
27830 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
27840 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
27850 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
27860 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
27870 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
27880 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
27890 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
278a0 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
278b0 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
278c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
278d0 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  str() interface 
278e0 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c  returns the Engl
278f0 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
27900 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69  t.** that descri
27910 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20  bes the [result 
27920 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e  code], as UTF-8.
27930 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
27940 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
27950 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
27960 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
27970 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20  lly.** and must 
27980 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20  not be freed by 
27990 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
279a0 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  ^..**.** When th
279b0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
279c0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
279d0 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
279e0 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
279f0 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
27a00 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
27a10 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
27a20 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
27a30 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
27a40 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
27a50 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
27a60 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
27a70 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
27a80 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
27a90 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
27aa0 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
27ab0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
27ac0 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
27ad0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
27ae0 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
27af0 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
27b00 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
27b10 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
27b20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
27b30 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
27b40 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
27b50 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
27b60 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
27b70 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
27b80 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
27b90 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
27ba0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
27bb0 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
27bc0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
27bd0 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
27be0 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
27bf0 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
27c00 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
27c10 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
27c20 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
27c30 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
27c40 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
27c50 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
27c60 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
27c70 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
27c80 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
27c90 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
27ca0 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
27cb0 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
27cc0 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51  ot be set..*/.SQ
27cd0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
27ce0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
27cf0 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69  te3_errcode(sqli
27d00 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45  te3 *db);.SQLITE
27d10 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
27d20 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
27d30 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
27d40 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53  (sqlite3 *db);.S
27d50 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
27d60 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
27d70 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72  CALL sqlite3_err
27d80 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53  msg(sqlite3*);.S
27d90 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
27da0 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44  void *SQLITE_STD
27db0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 72 72  CALL sqlite3_err
27dc0 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
27dd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
27de0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
27df0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65  TDCALL sqlite3_e
27e00 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
27e10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 72 65  ** CAPI3REF: Pre
27e20 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
27e30 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
27e40 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
27e50 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
27e60 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
27e70 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
27e80 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
27e90 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
27ea0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
27eb0 74 20 74 68 61 74 0a 2a 2a 20 68 61 73 20 62 65  t that.** has be
27ec0 65 6e 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f  en compiled into
27ed0 20 62 69 6e 61 72 79 20 66 6f 72 6d 20 61 6e 64   binary form and
27ee0 20 69 73 20 72 65 61 64 79 20 74 6f 20 62 65 20   is ready to be 
27ef0 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  evaluated..**.**
27f00 20 54 68 69 6e 6b 20 6f 66 20 65 61 63 68 20 53   Think of each S
27f10 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
27f20 61 20 73 65 70 61 72 61 74 65 20 63 6f 6d 70 75  a separate compu
27f30 74 65 72 20 70 72 6f 67 72 61 6d 2e 20 20 54 68  ter program.  Th
27f40 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
27f50 4c 20 74 65 78 74 20 69 73 20 73 6f 75 72 63 65  L text is source
27f60 20 63 6f 64 65 2e 20 20 41 20 70 72 65 70 61 72   code.  A prepar
27f70 65 64 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a  ed statement obj
27f80 65 63 74 20 0a 2a 2a 20 69 73 20 74 68 65 20 63  ect .** is the c
27f90 6f 6d 70 69 6c 65 64 20 6f 62 6a 65 63 74 20 63  ompiled object c
27fa0 6f 64 65 2e 20 20 41 6c 6c 20 53 51 4c 20 6d 75  ode.  All SQL mu
27fb0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20  st be converted 
27fc0 69 6e 74 6f 20 61 0a 2a 2a 20 70 72 65 70 61 72  into a.** prepar
27fd0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 62 65 66  ed statement bef
27fe0 6f 72 65 20 69 74 20 63 61 6e 20 62 65 20 72 75  ore it can be ru
27ff0 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66  n..**.** The lif
28000 65 2d 63 79 63 6c 65 20 6f 66 20 61 20 70 72 65  e-cycle of a pre
28010 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
28020 6f 62 6a 65 63 74 20 75 73 75 61 6c 6c 79 20 67  object usually g
28030 6f 65 73 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  oes like this:.*
28040 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
28050 3e 20 43 72 65 61 74 65 20 74 68 65 20 70 72 65  > Create the pre
28060 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
28070 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
28080 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
28090 28 29 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ()]..** <li> Bin
280a0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 70 61 72  d values to [par
280b0 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
280c0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
280d0 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
280e0 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
280f0 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
28100 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
28110 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
28120 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
28130 69 3e 20 52 65 73 65 74 20 74 68 65 20 70 72 65  i> Reset the pre
28140 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
28150 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
28160 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
28170 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
28180 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
28190 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
281a0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
281b0 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
281c0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
281d0 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
281e0 2f 6f 6c 3e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  /ol>.*/.typedef 
281f0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
28200 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
28210 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28220 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
28230 74 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ts.** METHOD: sq
28240 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  lite3.**.** ^(Th
28250 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
28260 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
28270 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
28280 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
28290 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
282a0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
282b0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
282c0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
282d0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
282e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
282f0 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
28300 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
28310 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
28320 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
28330 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
28340 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
28350 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
28360 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
28370 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
28380 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
28390 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
283a0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
283b0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
283c0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
283d0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
283e0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
283f0 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
28400 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
28410 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
28420 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
28430 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
28440 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
28450 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
28460 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
28470 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
28480 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
28490 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
284a0 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
284b0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
284c0 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
284d0 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
284e0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
284f0 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
28500 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
28510 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
28520 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
28530 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
28540 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
28550 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
28560 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
28570 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
28580 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
28590 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
285a0 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
285b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
285c0 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
285d0 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
285e0 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
285f0 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
28600 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
28610 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
28620 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
28630 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
28640 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
28650 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
28660 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
28670 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
28680 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
28690 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
286a0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
286b0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
286c0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
286d0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
286e0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
286f0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
28700 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
28710 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
28720 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
28730 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
28740 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
28750 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
28760 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
28770 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
28780 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
28790 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
287a0 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
287b0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
287c0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
287d0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
287e0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
287f0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
28800 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
28810 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
28820 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
28830 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
28840 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
28850 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
28860 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
28870 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
28880 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
28890 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
288a0 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
288b0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
288c0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
288d0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
288e0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
288f0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
28900 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
28910 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
28920 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
28930 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
28940 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
28950 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
28960 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
28970 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
28980 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
28990 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
289a0 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
289b0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
289c0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
289d0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
289e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
289f0 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
28a00 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
28a10 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
28a20 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
28a30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28a40 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
28a50 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
28a60 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
28a70 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
28a80 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
28a90 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
28aa0 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
28ab0 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
28ac0 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
28ad0 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
28ae0 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
28af0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
28b00 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
28b10 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
28b20 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
28b30 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
28b40 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
28b50 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
28b60 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
28b70 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
28b80 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
28b90 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
28ba0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
28bb0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
28bc0 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
28bd0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28be0 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
28bf0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
28c00 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20  r table row, in 
28c10 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a  bytes.<dd>)^.**.
28c20 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
28c30 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e  T_SQL_LENGTH]] ^
28c40 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
28c50 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
28c60 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
28c70 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
28c80 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
28c90 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
28ca0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
28cb0 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20  _LIMIT_COLUMN]] 
28cc0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
28cd0 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
28ce0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
28cf0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
28d00 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
28d10 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
28d20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
28d30 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
28d40 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
28d50 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
28d60 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
28d70 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
28d80 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
28d90 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
28da0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
28db0 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e  T_EXPR_DEPTH]] ^
28dc0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
28dd0 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
28de0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
28df0 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
28e00 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
28e10 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
28e20 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
28e30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
28e40 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28  OUND_SELECT]] ^(
28e50 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28e60 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
28e70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
28e80 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
28e90 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
28ea0 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
28eb0 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
28ec0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
28ed0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e  IMIT_VDBE_OP]] ^
28ee0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
28ef0 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
28f00 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
28f10 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
28f20 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
28f30 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
28f40 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
28f50 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
28f60 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  L statement.  Th
28f70 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  is limit is not 
28f80 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66  currently.** enf
28f90 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68  orced, though th
28fa0 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65  at might be adde
28fb0 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  d in some future
28fc0 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
28fd0 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  QLite.</dd>)^.**
28fe0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
28ff0 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
29000 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29010 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
29020 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
29030 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
29040 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
29050 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
29060 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
29070 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
29080 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  D]] ^(<dt>SQLITE
29090 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
290a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
290b0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
290c0 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
290d0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
290e0 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
290f0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
29100 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
29110 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
29120 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
29130 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
29140 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29150 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
29160 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
29170 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
29180 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
29190 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
291a0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
291b0 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
291c0 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  UMBER]].** ^(<dt
291d0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
291e0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
291f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
29200 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
29210 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
29220 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
29230 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
29240 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29250 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d  T_TRIGGER_DEPTH]
29260 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29270 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
29280 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29290 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
292a0 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
292b0 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
292c0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
292d0 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
292e0 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53  HREADS]] ^(<dt>S
292f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
29300 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a  ER_THREADS</dt>.
29310 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
29320 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78  um number of aux
29330 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68  iliary worker th
29340 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e  reads that a sin
29350 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  gle.** [prepared
29360 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20   statement] may 
29370 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  start.</dd>)^.**
29380 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
29390 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
293a0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
293b0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
293c0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
293d0 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
293e0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
293f0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29400 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
29410 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
29420 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29430 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
29440 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
29450 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29460 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
29470 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
29480 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29490 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
294a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
294b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
294c0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
294d0 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
294e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
294f0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
29500 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
29510 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
29520 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
29530 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
29540 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
29550 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
29560 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
29570 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
29580 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
29590 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
295a0 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
295b0 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
295c0 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20  _THREADS        
295d0 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     11../*.** CAP
295e0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
295f0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
29600 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
29610 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
29620 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  mpiler}.** METHO
29630 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f  D: sqlite3.** CO
29640 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
29650 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f  e3_stmt.**.** To
29660 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
29670 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
29680 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
29690 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
296a0 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
296b0 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
296c0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
296d0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
296e0 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
296f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29700 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
29710 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
29720 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
29730 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
29740 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
29750 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
29760 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
29770 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
29780 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
29790 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
297a0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
297b0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
297c0 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
297d0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
297e0 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
297f0 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
29800 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
29810 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
29820 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
29830 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
29840 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
29850 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
29860 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
29870 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
29880 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
29890 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
298a0 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
298b0 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69  gument is negati
298c0 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ve, then zSql is
298d0 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
298e0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
298f0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
29900 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c  yte is positive,
29910 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a   then it is the.
29920 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
29930 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
29940 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73  l.  ^If nByte is
29950 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70   zero, then no p
29960 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
29970 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65  ment is generate
29980 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
29990 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74  ler knows that t
299a0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
299b0 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
299c0 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  ated, then.** th
299d0 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70  ere is a small p
299e0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
299f0 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20  tage to passing 
29a00 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
29a10 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68  er that.** is th
29a20 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
29a30 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
29a40 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
29a50 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
29a60 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  l-terminator..**
29a70 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
29a80 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
29a90 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
29aa0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
29ab0 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
29ac0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
29ad0 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
29ae0 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
29af0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
29b00 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
29b10 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
29b20 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
29b30 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
29b40 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
29b50 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
29b60 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
29b70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
29b80 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
29b90 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
29ba0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
29bb0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
29bc0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
29bd0 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
29be0 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
29bf0 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
29c00 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
29c10 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
29c20 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
29c30 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
29c40 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
29c50 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
29c60 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
29c70 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
29c80 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
29c90 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
29ca0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
29cb0 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
29cc0 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
29cd0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
29ce0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
29cf0 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
29d00 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
29d10 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
29d20 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
29d30 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
29d40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
29d50 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
29d60 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
29d70 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
29d80 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
29d90 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
29da0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
29db0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
29dc0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
29dd0 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
29de0 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
29df0 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
29e00 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
29e10 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
29e20 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
29e30 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
29e40 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
29e50 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
29e60 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
29e70 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
29e80 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
29e90 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
29ea0 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
29eb0 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
29ec0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
29ed0 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
29ee0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
29ef0 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
29f00 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
29f10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
29f20 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
29f30 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
29f40 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
29f50 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
29f60 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
29f70 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
29f80 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
29f90 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
29fa0 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
29fb0 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
29fc0 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
29fd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
29fe0 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
29ff0 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
2a000 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
2a010 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
2a020 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61   it again. As ma
2a030 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41  ny as [SQLITE_MA
2a040 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a  X_SCHEMA_RETRY].
2a050 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20  ** retries will 
2a060 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c  occur before sql
2a070 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65  ite3_step() give
2a080 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73  s up and returns
2a090 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f   an error..** </
2a0a0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
2a0b0 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
2a0c0 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
2a0d0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
2a0e0 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
2a0f0 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
2a100 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
2a110 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2a120 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
2a130 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
2a140 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
2a150 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
2a160 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
2a170 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
2a180 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
2a190 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
2a1a0 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
2a1b0 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
2a1c0 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
2a1d0 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
2a1e0 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
2a1f0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
2a200 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
2a210 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
2a220 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
2a230 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
2a240 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
2a250 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
2a260 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
2a270 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
2a280 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2a290 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
2a2a0 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
2a2b0 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
2a2c0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2a2d0 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
2a2e0 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
2a2f0 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
2a300 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
2a310 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
2a320 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
2a330 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
2a340 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
2a350 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
2a360 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
2a370 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
2a380 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
2a390 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
2a3a0 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
2a3b0 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
2a3c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2a3d0 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
2a3e0 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
2a3f0 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
2a400 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
2a410 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
2a420 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
2a430 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
2a440 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
2a450 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
2a460 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2a470 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
2a480 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
2a490 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
2a4a0 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
2a4b0 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
2a4c0 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
2a4d0 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
2a4e0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2a4f0 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT3] compile-t
2a500 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
2a510 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  abled..** </li>.
2a520 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49  ** </ol>.*/.SQLI
2a530 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
2a540 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2a550 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
2a560 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2a570 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2a580 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a590 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2a5a0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2a5b0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2a5c0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2a5d0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2a5e0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2a5f0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2a600 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2a610 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2a620 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2a630 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2a640 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2a650 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2a660 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2a670 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2a680 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
2a690 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2a6a0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70  TDCALL sqlite3_p
2a6b0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
2a6c0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
2a6d0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
2a6e0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2a6f0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
2a700 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
2a710 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
2a720 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2a730 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2a740 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2a750 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2a760 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2a770 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2a780 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2a790 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2a7a0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
2a7b0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2a7c0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2a7d0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2a7e0 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
2a7f0 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2a800 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70  TDCALL sqlite3_p
2a810 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
2a820 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
2a830 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
2a840 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2a850 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
2a860 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
2a870 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
2a880 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
2a890 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
2a8a0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
2a8b0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
2a8c0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
2a8d0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
2a8e0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
2a8f0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
2a900 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
2a910 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
2a920 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
2a930 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
2a940 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
2a950 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2a960 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 70  TDCALL sqlite3_p
2a970 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
2a980 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
2a990 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
2a9a0 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
2a9b0 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
2a9c0 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
2a9d0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
2a9e0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2a9f0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2aa00 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2aa10 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2aa20 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2aa30 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2aa40 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2aa50 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2aa60 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
2aa70 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2aa80 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2aa90 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2aaa0 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
2aab0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
2aac0 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
2aad0 74 20 53 51 4c 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t SQL.** METHOD:
2aae0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2aaf0 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
2ab00 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
2ab10 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
2ab20 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
2ab30 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
2ab40 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
2ab50 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
2ab60 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
2ab70 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
2ab80 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
2ab90 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2aba0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2abb0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2abc0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
2abd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2abe0 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53  t char *SQLITE_S
2abf0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 73  TDCALL sqlite3_s
2ac00 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
2ac10 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2ac20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
2ac30 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74  ine If An SQL St
2ac40 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54  atement Writes T
2ac50 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20 4d  he Database.** M
2ac60 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73  ETHOD: sqlite3_s
2ac70 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  tmt.**.** ^The s
2ac80 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
2ac90 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63  only(X) interfac
2aca0 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
2acb0 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20  non-zero) if.** 
2acc0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
2acd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ace0 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20  ent] X makes no 
2acf0 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74  direct changes t
2ad00 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  o.** the content
2ad10 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2ad20 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74   file..**.** Not
2ad30 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74  e that [applicat
2ad40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2ad50 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a  functions] or.**
2ad60 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73   [virtual tables
2ad70 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74  ] might change t
2ad80 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69  he database indi
2ad90 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65  rectly as a side
2ada0 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28   effect.  .** ^(
2adb0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  For example, if 
2adc0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
2add0 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f  efines a functio
2ade0 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20  n "eval()" that 
2adf0 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74  .** calls [sqlit
2ae00 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e  e3_exec()], then
2ae10 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53   the following S
2ae20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75  QL statement wou
2ae30 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65  ld.** change the
2ae40 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
2ae50 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65  hrough side-effe
2ae60 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  cts:.**.** <bloc
2ae70 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
2ae80 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27     SELECT eval('
2ae90 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29  DELETE FROM t1')
2aea0 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70   FROM t2;.** </p
2aeb0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
2aec0 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75  .**.** But becau
2aed0 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20  se the [SELECT] 
2aee0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
2aef0 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ot change the da
2af00 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64  tabase file.** d
2af10 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33  irectly, sqlite3
2af20 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2af30 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74   would still ret
2af40 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a  urn true.)^.**.*
2af50 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63  * ^Transaction c
2af60 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74  ontrol statement
2af70 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e  s such as [BEGIN
2af80 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f  ], [COMMIT], [RO
2af90 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56  LLBACK],.** [SAV
2afa0 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45  EPOINT], and [RE
2afb0 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c  LEASE] cause sql
2afc0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2afd0 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
2afe0 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68  rue,.** since th
2aff0 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65  e statements the
2b000 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61  mselves do not a
2b010 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74  ctually modify t
2b020 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a  he database but.
2b030 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63  ** rather they c
2b040 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e  ontrol the timin
2b050 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20  g of when other 
2b060 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66  statements modif
2b070 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61  y the .** databa
2b080 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43  se.  ^The [ATTAC
2b090 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20  H] and [DETACH] 
2b0a0 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20  statements also 
2b0b0 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33  cause.** sqlite3
2b0c0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2b0d0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20   to return true 
2b0e0 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f  since, while tho
2b0f0 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  se statements.**
2b100 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66   change the conf
2b110 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64  iguration of a d
2b120 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2b130 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20  on, they do not 
2b140 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73  make .** changes
2b150 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   to the content 
2b160 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
2b170 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a  files on disk..*
2b180 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2b190 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2b1a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2b1b0 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
2b1c0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2b1d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
2b1e0 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
2b1f0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
2b200 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
2b210 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2b220 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2b230 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2b240 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
2b250 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
2b260 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
2b270 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2b280 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
2b290 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
2b2a0 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
2b2b0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2b2c0 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20  S)] but has not 
2b2d0 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
2b2e0 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74  n and/or has not
2b2f0 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20   .** been reset 
2b300 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
2b310 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
2b320 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2b330 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
2b340 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
2b350 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
2b360 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
2b370 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
2b380 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
2b390 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
2b3a0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
2b3b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2b3c0 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
2b3d0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2b3e0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2b3f0 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
2b400 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
2b410 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
2b420 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
2b430 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2b440 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
2b450 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
2b460 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
2b470 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
2b480 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
2b490 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
2b4a0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
2b4b0 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
2b4c0 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
2b4d0 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
2b4e0 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
2b4f0 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
2b500 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
2b510 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
2b520 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
2b530 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53  ction open..*/.S
2b540 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2b550 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2b560 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
2b570 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2b580 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b590 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
2b5a0 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
2b5b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
2b5c0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b5d0 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
2b5e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2b5f0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
2b600 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
2b610 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
2b620 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
2b630 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
2b640 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
2b650 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
2b660 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2b670 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
2b680 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
2b690 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
2b6a0 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
2b6b0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2b6c0 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
2b6d0 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
2b6e0 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
2b6f0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
2b700 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
2b710 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2b720 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
2b730 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
2b740 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
2b750 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
2b760 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
2b770 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2b780 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
2b790 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
2b7a0 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
2b7b0 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
2b7c0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2b7d0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
2b7e0 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
2b7f0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
2b800 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
2b810 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
2b820 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
2b830 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
2b840 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2b850 6c 75 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71  lue.  The.** [sq
2b860 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
2b870 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  )] interface can
2b880 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f 6e 73   be used to cons
2b890 74 72 75 63 74 20 61 20 6e 65 77 20 0a 2a 2a 20  truct a new .** 
2b8a0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2b8b0 33 5f 76 61 6c 75 65 20 66 72 6f 6d 20 61 6e 20  3_value from an 
2b8c0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2b8d0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
2b8e0 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
2b8f0 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
2b900 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
2b910 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
2b920 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
2b930 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
2b940 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
2b950 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
2b960 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2b970 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
2b980 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2b990 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
2b9a0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2b9b0 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
2b9c0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
2b9d0 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
2b9e0 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
2b9f0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
2ba00 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
2ba10 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2ba20 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
2ba30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
2ba40 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
2ba50 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
2ba60 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
2ba70 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2ba80 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
2ba90 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
2baa0 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
2bab0 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
2bac0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2bad0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2bae0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2baf0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2bb00 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
2bb10 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
2bb20 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
2bb30 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
2bb40 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
2bb50 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
2bb60 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
2bb70 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
2bb80 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
2bb90 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2bba0 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2bbb0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2bbc0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
2bbd0 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
2bbe0 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
2bbf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2bc00 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2bc10 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
2bc20 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
2bc30 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
2bc40 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
2bc50 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2bc60 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2bc70 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
2bc80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2bc90 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
2bca0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2bcb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2bcc0 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
2bcd0 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
2bce0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2bcf0 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
2bd00 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
2bd10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
2bd20 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
2bd30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2bd40 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
2bd50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2bd60 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
2bd70 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
2bd80 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
2bd90 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
2bda0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2bdb0 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
2bdc0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
2bdd0 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
2bde0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bdf0 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
2be00 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
2be10 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
2be20 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
2be30 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
2be40 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
2be50 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
2be60 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
2be70 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
2be80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2be90 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
2bea0 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
2beb0 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
2bec0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2bed0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
2bee0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2bef0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2bf00 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2bf10 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
2bf20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
2bf30 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
2bf40 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
2bf50 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
2bf60 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
2bf70 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2bf80 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
2bf90 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2bfa0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2bfb0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
2bfc0 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
2bfd0 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
2bfe0 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
2bff0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
2c000 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2c010 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
2c020 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
2c030 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
2c040 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
2c050 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
2c060 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
2c070 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
2c080 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
2c090 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
2c0a0 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2c0b0 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2c0c0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
2c0d0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
2c0e0 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
2c0f0 6e 67 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ng}.** METHOD: s
2c100 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2c110 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
2c120 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
2c130 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
2c140 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2c150 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
2c160 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
2c170 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
2c180 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
2c190 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
2c1a0 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
2c1b0 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
2c1c0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
2c1d0 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
2c1e0 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
2c1f0 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
2c200 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
2c210 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
2c220 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
2c230 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
2c240 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
2c250 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
2c260 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
2c270 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
2c280 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
2c290 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
2c2a0 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
2c2b0 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
2c2c0 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
2c2d0 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
2c2e0 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
2c2f0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
2c300 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2c310 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
2c320 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2c330 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2c340 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2c350 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
2c360 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
2c370 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
2c380 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
2c390 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
2c3a0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2c3b0 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
2c3c0 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
2c3d0 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
2c3e0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
2c3f0 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
2c400 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
2c410 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
2c420 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
2c430 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
2c440 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
2c450 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
2c460 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
2c470 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
2c480 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
2c490 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
2c4a0 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
2c4b0 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
2c4c0 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
2c4d0 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
2c4e0 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
2c4f0 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
2c500 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
2c510 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
2c520 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2c530 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
2c540 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
2c550 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
2c560 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
2c570 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
2c580 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
2c590 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
2c5a0 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
2c5b0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
2c5c0 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
2c5d0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
2c5e0 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
2c5f0 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
2c600 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
2c610 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
2c620 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
2c630 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2c640 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
2c650 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
2c660 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2c670 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
2c680 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
2c690 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  or sqlite3_bind_
2c6a0 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55 4c 4c  blob() is a NULL
2c6b0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
2c6c0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2c6d0 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72 65 64  er.** is ignored
2c6e0 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72 65 73   and the end res
2c6f0 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d 65 20  ult is the same 
2c700 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  as sqlite3_bind_
2c710 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  null()..**.** ^(
2c720 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65  In those routine
2c730 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66 6f  s that have a fo
2c740 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69  urth argument, i
2c750 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a  ts value is the.
2c760 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
2c770 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  es in the parame
2c780 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61  ter.  To be clea
2c790 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  r: the value is 
2c7a0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
2c7b0 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e   <u>bytes</u> in
2c7c0 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20   the value, not 
2c7d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
2c7e0 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e  aracters.)^.** ^
2c7f0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
2c800 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2c810 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f  e3_bind_text() o
2c820 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2c830 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65  ext16().** is ne
2c840 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65  gative, then the
2c850 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 73   length of the s
2c860 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20  tring is.** the 
2c870 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2c880 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  up to the first 
2c890 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
2c8a0 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75 72 74  .** If the fourt
2c8b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
2c8c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2c8d0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  () is negative, 
2c8e0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61  then.** the beha
2c8f0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
2c900 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e  d..** If a non-n
2c910 65 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70  egative fourth p
2c920 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76  arameter is prov
2c930 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f  ided to sqlite3_
2c940 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f  bind_text().** o
2c950 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  r sqlite3_bind_t
2c960 65 78 74 31 36 28 29 20 6f 72 20 73 71 6c 69 74  ext16() or sqlit
2c970 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29  e3_bind_text64()
2c980 20 74 68 65 6e 0a 2a 2a 20 74 68 61 74 20 70 61   then.** that pa
2c990 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20  rameter must be 
2c9a0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 0a  the byte offset.
2c9b0 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ** where the NUL
2c9c0 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
2c9d0 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e 67  d occur assuming
2c9e0 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72 65   the string were
2c9f0 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61 74   NUL.** terminat
2ca00 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20  ed.  If any NUL 
2ca10 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72  characters occur
2ca20 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74 73   at byte offsets
2ca30 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20 74   less than .** t
2ca40 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2ca50 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2ca60 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
2ca70 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75 65  ing string value
2ca80 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e   will.** contain
2ca90 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e 20   embedded NULs. 
2caa0 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20 65   The result of e
2cab0 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f 6c  xpressions invol
2cac0 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a 20  ving strings.** 
2cad0 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55  with embedded NU
2cae0 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  Ls is undefined.
2caf0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74  .**.** ^The fift
2cb00 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  h argument to th
2cb10 65 20 42 4c 4f 42 20 61 6e 64 20 73 74 72 69 6e  e BLOB and strin
2cb20 67 20 62 69 6e 64 69 6e 67 20 69 6e 74 65 72 66  g binding interf
2cb30 61 63 65 73 0a 2a 2a 20 69 73 20 61 20 64 65 73  aces.** is a des
2cb40 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
2cb50 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2cb60 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
2cb70 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
2cb80 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2cb90 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
2cba0 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
2cbb0 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
2cbc0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
2cbd0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
2cbe0 61 6c 6c 20 74 6f 20 62 69 6e 64 20 41 50 49 20  all to bind API 
2cbf0 66 61 69 6c 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  fails..** ^If th
2cc00 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2cc10 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69   is.** the speci
2cc20 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  al value [SQLITE
2cc30 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53  _STATIC], then S
2cc40 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
2cc50 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d  at the.** inform
2cc60 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74  ation is in stat
2cc70 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70  ic, unmanaged sp
2cc80 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  ace and does not
2cc90 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65   need to be free
2cca0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  d..** ^If the fi
2ccb0 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73  fth argument has
2ccc0 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49   the value [SQLI
2ccd0 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74  TE_TRANSIENT], t
2cce0 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61  hen.** SQLite ma
2ccf0 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76  kes its own priv
2cd00 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
2cd10 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79  data immediately
2cd20 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20  , before.** the 
2cd30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2cd40 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2cd50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ..**.** ^The six
2cd60 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2cd70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2cd80 36 34 28 29 20 6d 75 73 74 20 62 65 20 6f 6e 65  64() must be one
2cd90 20 6f 66 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55   of.** [SQLITE_U
2cda0 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
2cdb0 46 31 36 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  F16], [SQLITE_UT
2cdc0 46 31 36 42 45 5d 2c 20 6f 72 20 5b 53 51 4c 49  F16BE], or [SQLI
2cdd0 54 45 5f 55 54 46 31 36 4c 45 5d 0a 2a 2a 20 74  TE_UTF16LE].** t
2cde0 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 65 6e  o specify the en
2cdf0 63 6f 64 69 6e 67 20 6f 66 20 74 68 65 20 74 65  coding of the te
2ce00 78 74 20 69 6e 20 74 68 65 20 74 68 69 72 64 20  xt in the third 
2ce10 70 61 72 61 6d 65 74 65 72 2e 20 20 49 66 0a 2a  parameter.  If.*
2ce20 2a 20 74 68 65 20 73 69 78 74 68 20 61 72 67 75  * the sixth argu
2ce30 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
2ce40 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 69 73  bind_text64() is
2ce50 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
2ce60 2a 2a 20 61 6c 6c 6f 77 65 64 20 76 61 6c 75 65  ** allowed value
2ce70 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 2c 20 6f  s shown above, o
2ce80 72 20 69 66 20 74 68 65 20 74 65 78 74 20 65 6e  r if the text en
2ce90 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72  coding is differ
2cea0 65 6e 74 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ent.** from the 
2ceb0 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
2cec0 65 64 20 62 79 20 74 68 65 20 73 69 78 74 68 20  ed by the sixth 
2ced0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
2cee0 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
2cef0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
2cf00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2cf10 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 29  _bind_zeroblob()
2cf20 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20 61   routine binds a
2cf30 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68 20   BLOB of length 
2cf40 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69 6c  N that.** is fil
2cf50 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73 2e  led with zeroes.
2cf60 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75 73    ^A zeroblob us
2cf70 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75 6e  es a fixed amoun
2cf80 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28  t of memory.** (
2cf90 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72 20  just an integer 
2cfa0 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a 65  to hold its size
2cfb0 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62 65  ) while it is be
2cfc0 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a 2a  ing processed..*
2cfd0 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65 20  * Zeroblobs are 
2cfe0 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72 76  intended to serv
2cff0 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65 72  e as placeholder
2d000 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f 73  s for BLOBs whos
2d010 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73 20  e.** content is 
2d020 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75 73  later written us
2d030 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2d040 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72  blob_open | incr
2d050 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f  emental BLOB I/O
2d060 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e  ] routines..** ^
2d070 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75 65  A negative value
2d080 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c 6f   for the zeroblo
2d090 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20 7a  b results in a z
2d0a0 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 2e  ero-length BLOB.
2d0b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20 6f  .**.** ^If any o
2d0c0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  f the sqlite3_bi
2d0d0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2d0e0 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68 20  are called with 
2d0f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2d100 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70 61  * for the [prepa
2d110 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
2d120 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72 65  r with a prepare
2d130 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72 20  d statement for 
2d140 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74 65  which.** [sqlite
2d150 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62 65  3_step()] has be
2d160 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20 72  en called more r
2d170 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73 71  ecently than [sq
2d180 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 0a  lite3_reset()],.
2d190 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** then the call
2d1a0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
2d1b0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 49  LITE_MISUSE].  I
2d1c0 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62 69  f any sqlite3_bi
2d1d0 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  nd_().** routine
2d1e0 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70 72   is passed a [pr
2d1f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d200 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e 20  ] that has been 
2d210 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a 2a  finalized, the.*
2d220 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  * result is unde
2d230 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
2d240 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a  ly harmful..**.*
2d250 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65 20  * ^Bindings are 
2d260 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20 74  not cleared by t
2d270 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
2d280 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a  t()] routine..**
2d290 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d 65   ^Unbound parame
2d2a0 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70 72  ters are interpr
2d2b0 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a  eted as NULL..**
2d2c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2d2d0 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65 73  _bind_* routines
2d2e0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2d2f0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 6f  OK] on success o
2d300 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20 63  r an.** [error c
2d310 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e 67  ode] if anything
2d320 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20   goes wrong..** 
2d330 5e 5b 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 5d  ^[SQLITE_TOOBIG]
2d340 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
2d350 65 64 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f  ed if the size o
2d360 66 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  f a string or BL
2d370 4f 42 0a 2a 2a 20 65 78 63 65 65 64 73 20 6c 69  OB.** exceeds li
2d380 6d 69 74 73 20 69 6d 70 6f 73 65 64 20 62 79 20  mits imposed by 
2d390 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
2d3a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
2d3b0 4e 47 54 48 5d 29 20 6f 72 0a 2a 2a 20 5b 53 51  NGTH]) or.** [SQ
2d3c0 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 5d  LITE_MAX_LENGTH]
2d3d0 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
2d3e0 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
2d3f0 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
2d400 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
2d410 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
2d420 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
2d430 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
2d440 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
2d450 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2d460 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2d470 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
2d480 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2d490 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
2d4a0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
2d4b0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2d4c0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
2d4d0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2d4e0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2d4f0 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
2d500 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2d510 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
2d520 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
2d530 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  ));.SQLITE_API i
2d540 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  nt SQLITE_STDCAL
2d550 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  L sqlite3_bind_b
2d560 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74  lob64(sqlite3_st
2d570 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2d580 76 6f 69 64 2a 2c 20 73 71 6c 69 74 65 33 5f 75  void*, sqlite3_u
2d590 69 6e 74 36 34 2c 0a 20 20 20 20 20 20 20 20 20  int64,.         
2d5a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
2d5b0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2d5c0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
2d5d0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
2d5e0 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c  lite3_bind_doubl
2d5f0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2d600 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53   int, double);.S
2d610 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2d620 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2d630 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71  ite3_bind_int(sq
2d640 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2d650 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
2d660 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2d670 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2d680 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
2d690 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
2d6a0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c  ite3_int64);.SQL
2d6b0 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49  ITE_API int SQLI
2d6c0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2d6d0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
2d6e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2d6f0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2d700 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
2d710 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2d720 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2d730 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
2d740 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
2d750 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
2d760 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2d770 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  LL sqlite3_bind_
2d780 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2d790 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2d7a0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
2d7b0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
2d7c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c  LITE_API int SQL
2d7d0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
2d7e0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2d7f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2d800 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
2d810 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2d820 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2d830 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2d840 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e  )(void*), unsign
2d850 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67  ed char encoding
2d860 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2d870 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  t SQLITE_STDCALL
2d880 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61   sqlite3_bind_va
2d890 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2d8a0 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71  *, int, const sq
2d8b0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
2d8c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2d8d0 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2d8e0 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2d8f0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2d900 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 53  , int, int n);.S
2d910 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
2d920 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
2d930 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2d940 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  ob64(sqlite3_stm
2d950 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
2d960 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a 2a 2a  _uint64);../*.**
2d970 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2d980 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74  r Of SQL Paramet
2d990 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ers.** METHOD: s
2d9a0 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2d9b0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
2d9c0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66  can be used to f
2d9d0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
2d9e0 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  f [SQL parameter
2d9f0 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70  s].** in a [prep
2da00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2da10 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73    SQL parameters
2da20 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74   are tokens of t
2da30 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20  he.** form "?", 
2da40 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20  "?NNN", ":AAA", 
2da50 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41  "$AAA", or "@AAA
2da60 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a  " that serve as.
2da70 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20  ** placeholders 
2da80 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20  for values that 
2da90 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  are [sqlite3_bin
2daa0 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a  d_blob | bound].
2dab0 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  ** to the parame
2dac0 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20  ters at a later 
2dad0 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  time..**.** ^(Th
2dae0 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61  is routine actua
2daf0 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20  lly returns the 
2db00 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72  index of the lar
2db10 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29  gest (rightmost)
2db20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46  .** parameter. F
2db30 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63  or all forms exc
2db40 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77  ept ?NNN, this w
2db50 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74  ill correspond t
2db60 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  o the.** number 
2db70 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65  of unique parame
2db80 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65  ters.  If parame
2db90 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e  ters of the ?NNN
2dba0 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a   form are used,.
2dbb0 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20  ** there may be 
2dbc0 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74  gaps in the list
2dbd0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
2dbe0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2dbf0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2dc00 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2dc10 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2dc20 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a  er_name()], and.
2dc30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2dc40 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2dc50 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2dc60 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
2dc70 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62 69  DCALL sqlite3_bi
2dc80 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2dc90 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2dca0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2dcb0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
2dcc0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 20  st Parameter.** 
2dcd0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2dce0 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2dcf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2dd00 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
2dd10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2dd20 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
2dd30 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
2dd40 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
2dd50 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2dd60 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
2dd70 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
2dd80 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
2dd90 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2dda0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2ddb0 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
2ddc0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
2ddd0 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
2dde0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2ddf0 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
2de00 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
2de10 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
2de20 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
2de30 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
2de40 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
2de50 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
2de60 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
2de70 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2de80 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
2de90 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
2dea0 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
2deb0 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
2dec0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
2ded0 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
2dee0 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
2def0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
2df00 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
2df10 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
2df20 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
2df30 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
2df40 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
2df50 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
2df60 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
2df70 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
2df80 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
2df90 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2dfa0 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
2dfb0 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
2dfc0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
2dfd0 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
2dfe0 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
2dff0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
2e000 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
2e010 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
2e020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2e030 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2e040 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2e050 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2e060 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2e070 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2e080 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2e090 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2e0a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2e0b0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2e0c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2e0d0 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
2e0e0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2e0f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2e100 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2e110 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
2e120 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
2e130 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
2e140 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
2e150 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  e.** METHOD: sql
2e160 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2e170 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65  ^Return the inde
2e180 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61  x of an SQL para
2e190 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20  meter given its 
2e1a0 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69  name.  ^The.** i
2e1b0 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72  ndex value retur
2e1c0 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20  ned is suitable 
2e1d0 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73  for use as the s
2e1e0 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74  econd.** paramet
2e1f0 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62  er to [sqlite3_b
2e200 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2e210 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65  _bind()].  ^A ze
2e220 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  ro.** is returne
2e230 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67  d if no matching
2e240 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f   parameter is fo
2e250 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  und.  ^The param
2e260 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73  eter.** name mus
2e270 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54  t be given in UT
2e280 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20  F-8 even if the 
2e290 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
2e2a0 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72  nt.** was prepar
2e2b0 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74  ed from UTF-16 t
2e2c0 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ext using [sqlit
2e2d0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2e2e0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
2e2f0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2e300 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2e310 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2e320 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2e330 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
2e340 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2e350 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2e360 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
2e370 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
2e380 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 62  TDCALL sqlite3_b
2e390 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2e3a0 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
2e3b0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
2e3c0 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
2e3d0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
2e3e0 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
2e3f0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2e400 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  nt.** METHOD: sq
2e410 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
2e420 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20 74 68   ^Contrary to th
2e430 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d  e intuition of m
2e440 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65  any, [sqlite3_re
2e450 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20  set()] does not 
2e460 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71  reset.** the [sq
2e470 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2e480 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61  | bindings] on a
2e490 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e4a0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74  ment]..** ^Use t
2e4b0 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f 20 72  his routine to r
2e4c0 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20 70 61  eset all host pa
2e4d0 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c  rameters to NULL
2e4e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2e4f0 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
2e500 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72  LL sqlite3_clear
2e510 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
2e520 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2e530 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2e540 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20  r Of Columns In 
2e550 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 20  A Result Set.** 
2e560 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2e570 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  stmt.**.** ^Retu
2e580 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
2e590 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2e5a0 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
2e5b0 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
2e5c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e5d0 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
2e5e0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
2e5f0 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
2e600 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
2e610 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
2e620 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
2e630 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
2e640 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2e650 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
2e660 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54  ount()].*/.SQLIT
2e670 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
2e680 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2e690 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
2e6a0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2e6b0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e6c0 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
2e6d0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2e6e0 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c  t.** METHOD: sql
2e6f0 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20  ite3_stmt.**.** 
2e700 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2e710 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2e720 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
2e730 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
2e740 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
2e750 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
2e760 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
2e770 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
2e780 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
2e790 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2e7a0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
2e7b0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
2e7c0 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
2e7d0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2e7e0 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
2e7f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2e800 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2e810 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
2e820 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
2e830 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2e840 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e850 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
2e860 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
2e870 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
2e880 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
2e890 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
2e8a0 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
2e8b0 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
2e8c0 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
2e8d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
2e8e0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
2e8f0 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
2e900 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
2e910 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e920 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
2e930 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
2e940 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
2e950 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
2e960 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
2e970 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
2e980 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
2e990 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2e9a0 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
2e9b0 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
2e9c0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
2e9d0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
2e9e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2e9f0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
2ea00 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
2ea10 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
2ea20 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
2ea30 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
2ea40 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
2ea50 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
2ea60 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
2ea70 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
2ea80 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
2ea90 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
2eaa0 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
2eab0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2eac0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2ead0 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
2eae0 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
2eaf0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2eb00 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
2eb10 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
2eb20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
2eb30 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
2eb40 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
2eb50 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
2eb60 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
2eb70 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
2eb80 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
2eb90 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
2eba0 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
2ebb0 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53  o the next..*/.S
2ebc0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2ebd0 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
2ebe0 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
2ebf0 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
2ec00 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2ec10 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2ec20 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54   void *SQLITE_ST
2ec30 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f  DCALL sqlite3_co
2ec40 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
2ec50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2ec60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ec70 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
2ec80 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
2ec90 73 75 6c 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  sult.** METHOD: 
2eca0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2ecb0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2ecc0 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
2ecd0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
2ece0 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
2ecf0 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
2ed00 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
2ed10 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
2ed20 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
2ed30 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
2ed40 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2ed50 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
2ed60 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2ed70 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
2ed80 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
2ed90 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
2eda0 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
2edb0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2edc0 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
2edd0 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
2ede0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
2edf0 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
2ee00 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2ee10 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
2ee20 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
2ee30 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2ee40 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
2ee50 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2ee60 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
2ee70 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
2ee80 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ee90 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
2eea0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
2eeb0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2eec0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2eed0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2eee0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2eef0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2ef00 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2ef10 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2ef20 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2ef30 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
2ef40 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
2ef50 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
2ef60 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
2ef70 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
2ef80 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
2ef90 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
2efa0 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
2efb0 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
2efc0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
2efd0 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
2efe0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2eff0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2f000 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
2f010 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2f020 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
2f030 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2f040 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2f050 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
2f060 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
2f070 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
2f080 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
2f090 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
2f0a0 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
2f0b0 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
2f0c0 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
2f0d0 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
2f0e0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
2f0f0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
2f100 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2f110 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
2f120 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
2f130 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
2f140 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
2f150 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
2f160 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
2f170 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
2f180 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
2f190 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
2f1a0 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
2f1b0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2f1c0 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
2f1d0 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
2f1e0 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
2f1f0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
2f200 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
2f210 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
2f220 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
2f230 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
2f240 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
2f250 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
2f260 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
2f270 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
2f280 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
2f290 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
2f2a0 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
2f2b0 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
2f2c0 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
2f2d0 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
2f2e0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
2f2f0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
2f300 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
2f310 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
2f320 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
2f330 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
2f340 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
2f350 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
2f360 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
2f370 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
2f380 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
2f390 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
2f3a0 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
2f3b0 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
2f3c0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
2f3d0 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
2f3e0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2f3f0 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
2f400 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2f410 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
2f420 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
2f430 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
2f440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2f450 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
2f460 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
2f470 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
2f480 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
2f490 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
2f4a0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
2f4b0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2f4c0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2f4d0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2f4e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2f4f0 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
2f500 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2f510 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61  e3_column_databa
2f520 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  se_name(sqlite3_
2f530 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2f540 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2f550 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
2f560 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  L sqlite3_column
2f570 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
2f580 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2f590 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2f5a0 63 6f 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49  const char *SQLI
2f5b0 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2f5c0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2f5d0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2f5e0 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2f5f0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2f600 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
2f610 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2f620 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
2f630 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2f640 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2f650 63 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44  char *SQLITE_STD
2f660 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
2f670 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28  umn_origin_name(
2f680 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2f690 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2f6a0 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
2f6b0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
2f6c0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2f6d0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2f6e0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
2f6f0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
2f700 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
2f710 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2f720 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2f730 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28  e3_stmt.**.** ^(
2f740 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
2f750 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
2f760 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2f770 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
2f780 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
2f790 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
2f7a0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
2f7b0 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
2f7c0 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
2f7d0 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
2f7e0 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
2f7f0 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
2f800 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2f810 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
2f820 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
2f830 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
2f840 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
2f850 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2f860 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
2f870 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
2f880 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2f890 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
2f8a0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2f8b0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
2f8c0 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2f8d0 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
2f8e0 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
2f8f0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
2f900 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
2f910 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
2f920 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
2f930 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
2f940 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
2f950 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
2f960 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
2f970 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
2f980 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
2f990 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
2f9a0 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
2f9b0 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
2f9c0 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
2f9d0 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
2f9e0 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
2f9f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
2fa00 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
2fa10 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
2fa20 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
2fa30 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
2fa40 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
2fa50 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
2fa60 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
2fa70 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
2fa80 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
2fa90 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
2faa0 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
2fab0 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
2fac0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
2fad0 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
2fae0 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
2faf0 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
2fb00 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
2fb10 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
2fb20 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
2fb30 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
2fb40 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
2fb50 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
2fb60 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
2fb70 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
2fb80 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
2fb90 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2fba0 6e 73 74 20 63 68 61 72 20 2a 53 51 4c 49 54 45  nst char *SQLITE
2fbb0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
2fbc0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2fbd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2fbe0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2fbf0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49  const void *SQLI
2fc00 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
2fc10 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2fc20 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
2fc30 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2fc40 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
2fc50 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
2fc60 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ent.** METHOD: s
2fc70 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
2fc80 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
2fc90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
2fca0 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
2fcb0 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
2fcc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2fcd0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2fce0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2fcf0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
2fd00 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2fd10 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
2fd20 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
2fd30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2fd40 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
2fd50 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
2fd60 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
2fd70 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
2fd80 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
2fd90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
2fda0 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
2fdb0 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
2fdc0 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
2fdd0 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
2fde0 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
2fdf0 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
2fe00 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
2fe10 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
2fe20 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
2fe30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2fe40 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2fe50 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
2fe60 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
2fe70 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
2fe80 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2fe90 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2fea0 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
2feb0 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
2fec0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2fed0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
2fee0 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
2fef0 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
2ff00 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2ff10 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
2ff20 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
2ff30 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
2ff40 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
2ff50 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2ff60 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
2ff70 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
2ff80 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
2ff90 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
2ffa0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
2ffb0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2ffc0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
2ffd0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
2ffe0 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
2fff0 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
30000 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
30010 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
30020 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
30030 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
30040 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
30050 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
30060 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
30070 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
30080 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
30090 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
300a0 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
300b0 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
300c0 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
300d0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
300e0 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
300f0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
30100 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
30110 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
30120 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
30130 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
30140 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
30150 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
30160 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
30170 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
30180 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
30190 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
301a0 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
301b0 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
301c0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
301d0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
301e0 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
301f0 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
30200 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
30210 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
30220 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
30230 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
30240 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
30250 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
30260 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
30270 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
30280 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
30290 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
302a0 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
302b0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
302c0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
302d0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
302e0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
302f0 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
30300 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
30310 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
30320 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
30330 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
30340 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
30350 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
30360 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
30370 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
30380 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
30390 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
303a0 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
303b0 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
303c0 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
303d0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
303e0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
303f0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
30400 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
30410 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
30420 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
30430 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
30440 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
30450 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
30460 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
30470 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
30480 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
30490 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
304a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
304b0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
304c0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
304d0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
304e0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
304f0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
30500 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
30510 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
30520 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
30530 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
30540 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
30550 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
30560 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
30570 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
30580 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
30590 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
305a0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
305b0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
305c0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
305d0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
305e0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
305f0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
30600 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
30610 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
30620 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
30630 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
30640 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
30650 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
30660 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
30670 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
30680 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
30690 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
306a0 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
306b0 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
306c0 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
306d0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
306e0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
306f0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
30700 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
30710 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
30720 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
30730 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
30740 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
30750 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
30760 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
30770 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
30780 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
30790 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
307a0 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
307b0 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
307c0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
307d0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
307e0 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
307f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
30800 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
30810 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
30820 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
30830 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
30840 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
30850 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
30860 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
30870 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
30880 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
30890 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
308a0 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
308b0 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
308c0 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
308d0 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
308e0 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
308f0 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
30900 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
30910 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
30920 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
30930 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
30940 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
30950 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
30960 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
30970 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
30980 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
30990 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
309a0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
309b0 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
309c0 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
309d0 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
309e0 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
309f0 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
30a00 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
30a10 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
30a20 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
30a30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
30a40 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
30a50 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
30a60 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
30a70 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
30a80 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
30a90 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
30aa0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
30ab0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
30ac0 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
30ad0 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
30ae0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
30af0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
30b00 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
30b10 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
30b20 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
30b30 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
30b40 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
30b50 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
30b60 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
30b70 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
30b80 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
30b90 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
30ba0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
30bb0 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
30bc0 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
30bd0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
30be0 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
30bf0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
30c00 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
30c10 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
30c20 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
30c30 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
30c40 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
30c50 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
30c60 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
30c70 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
30c80 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
30c90 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
30ca0 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
30cb0 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
30cc0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
30cd0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
30ce0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
30cf0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
30d00 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
30d10 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
30d20 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
30d30 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
30d40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
30d50 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
30d60 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
30d70 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
30d80 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
30d90 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
30da0 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69  qlite3_step(sqli
30db0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
30dc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
30dd0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
30de0 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a  n a result set.*
30df0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
30e00 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  3_stmt.**.** ^Th
30e10 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
30e20 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63  ount(P) interfac
30e30 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
30e40 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
30e50 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  in the.** curren
30e60 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73  t row of the res
30e70 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70  ult set of [prep
30e80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
30e90 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72  P..** ^If prepar
30ea0 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64  ed statement P d
30eb0 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73  oes not have res
30ec0 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65  ults ready to re
30ed0 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c  turn.** (via cal
30ee0 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ls to the [sqlit
30ef0 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20  e3_column_int | 
30f00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a  sqlite3_column_*
30f10 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66  ()] of.** interf
30f20 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74  aces) then sqlit
30f30 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
30f40 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e   returns 0..** ^
30f50 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
30f60 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
30f70 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30  e also returns 0
30f80 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20   if P is a NULL 
30f90 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65  pointer..** ^The
30fa0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
30fb0 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72  unt(P) routine r
30fc0 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20  eturns 0 if the 
30fd0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
30fe0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
30ff0 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b  p](P) returned [
31000 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e  SQLITE_DONE].  ^
31010 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
31020 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c  _count(P).** wil
31030 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72  l return non-zer
31040 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61  o if previous ca
31050 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
31060 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
31070 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  .** [SQLITE_ROW]
31080 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20  , except in the 
31090 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41  case of the [PRA
310a0 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f  GMA incremental_
310b0 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65  vacuum].** where
310c0 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
310d0 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61  ns zero since ea
310e0 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20  ch step of that 
310f0 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72  multi-step.** pr
31100 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63  agma returns 0 c
31110 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a  olumns of data..
31120 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
31130 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
31140 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49  count()].*/.SQLI
31150 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
31160 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
31170 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
31180 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
31190 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
311a0 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
311b0 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
311c0 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
311d0 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
311e0 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
311f0 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
31200 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
31210 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
31220 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
31230 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
31240 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
31250 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
31260 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
31270 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
31280 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
31290 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
312a0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
312b0 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
312c0 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
312d0 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
312e0 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
312f0 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
31300 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
31310 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
31320 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
31330 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
31340 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
31350 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
31360 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
31370 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
31380 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
31390 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
313a0 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
313b0 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
313c0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
313d0 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
313e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
313f0 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
31400 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
31410 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
31420 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
31430 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
31440 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
31450 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
31460 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
31470 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
31480 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
31490 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
314a0 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
314b0 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
314c0 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
314d0 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
314e0 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54  unctions}.** MET
314f0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d  HOD: sqlite3_stm
31500 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
31510 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
31520 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
31530 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
31540 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
31550 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
31560 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
31570 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
31580 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
31590 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
315a0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
315b0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
315c0 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
315d0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
315e0 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
315f0 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
31600 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
31610 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
31620 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
31630 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
31640 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
31650 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
31660 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
31670 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
31680 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
31690 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
316a0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
316b0 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
316c0 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
316d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
316e0 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
316f0 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
31700 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
31710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
31720 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
31730 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
31740 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
31750 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
31760 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
31770 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
31780 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
31790 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
317a0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
317b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
317c0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
317d0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
317e0 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
317f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
31800 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
31810 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
31820 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
31830 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
31840 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
31850 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
31860 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
31870 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
31880 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
31890 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
318a0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
318b0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
318c0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
318d0 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
318e0 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
318f0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
31900 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
31910 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
31920 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
31930 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
31940 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
31950 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
31960 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
31970 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
31980 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
31990 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
319a0 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
319b0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
319c0 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
319d0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
319e0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
319f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31a00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
31a10 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
31a20 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
31a30 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
31a40 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
31a50 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
31a60 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
31a70 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
31a80 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
31a90 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
31aa0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
31ab0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
31ac0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
31ad0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
31ae0 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
31af0 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
31b00 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
31b10 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
31b20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
31b30 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
31b40 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
31b50 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
31b60 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
31b70 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
31b80 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
31b90 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
31ba0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
31bb0 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
31bc0 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
31bd0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
31be0 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
31bf0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
31c00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
31c10 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
31c20 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
31c30 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
31c40 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
31c50 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
31c60 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
31c70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31c80 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
31c90 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
31ca0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
31cb0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
31cc0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
31cd0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
31ce0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
31cf0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31d00 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
31d10 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
31d20 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
31d30 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
31d40 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
31d50 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
31d60 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
31d70 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
31d80 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
31d90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
31da0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
31db0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
31dc0 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
31dd0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
31de0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
31df0 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
31e00 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
31e10 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
31e20 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
31e30 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
31e40 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
31e50 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
31e60 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
31e70 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
31e80 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
31e90 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
31ea0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
31eb0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
31ec0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
31ed0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
31ee0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
31ef0 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
31f00 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
31f10 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
31f20 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
31f30 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
31f40 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
31f50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
31f60 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
31f70 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
31f80 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
31f90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31fa0 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
31fb0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
31fc0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
31fd0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
31fe0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
31ff0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
32000 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
32010 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
32020 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
32030 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
32040 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32050 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
32060 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
32070 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
32080 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
32090 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
320a0 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
320b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
320c0 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
320d0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
320e0 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
320f0 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
32100 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
32110 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
32120 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
32130 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32140 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
32150 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
32160 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
32170 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
32180 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
32190 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
321a0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
321b0 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
321c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
321d0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
321e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
321f0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
32200 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
32210 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
32220 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
32230 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
32240 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
32250 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
32260 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
32270 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
32280 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  inter..**.** <b>
32290 57 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68  Warning:</b> ^Th
322a0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
322b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
322c0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
322d0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
322e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
322f0 65 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61  e] object.  In a
32300 20 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65   multithreaded e
32310 6e 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61  nvironment,.** a
32320 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
32330 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
32340 63 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ct may only be u
32350 73 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a  sed safely with.
32360 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
32370 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
32380 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
32390 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
323a0 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
323b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
323c0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
323d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
323e0 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
323f0 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
32400 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
32410 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
32420 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
32430 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
32440 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
32450 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
32460 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
32470 79 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68  ytes()], the beh
32480 61 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72  avior is not thr
32490 65 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54  eadsafe..**.** T
324a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
324b0 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
324c0 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
324d0 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e   appropriate.  ^
324e0 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
324f0 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
32500 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
32510 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
32520 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
32530 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
32540 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
32550 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
32560 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
32570 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
32580 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
32590 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
325a0 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
325b0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
325c0 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
325d0 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
325e0 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
325f0 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
32600 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
32610 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
32620 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
32630 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
32640 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
32650 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
32660 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
32670 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
32680 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
32690 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
326a0 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
326b0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
326c0 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
326d0 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
326e0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
326f0 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
32700 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
32710 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
32720 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
32730 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
32740 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
32750 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
32760 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
32770 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
32780 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
32790 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
327a0 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
327b0 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
327c0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
327d0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
327e0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
327f0 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
32800 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
32810 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
32820 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
32830 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
32840 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
32850 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
32860 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
32870 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
32880 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
32890 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
328a0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  LOB    <td> [CAS
328b0 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74  T] to BLOB.** <t
328c0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
328d0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
328e0 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
328f0 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
32900 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
32910 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
32920 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
32930 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
32940 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
32950 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
32960 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
32970 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
32980 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
32990 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
329a0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
329b0 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
329c0 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
329d0 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
329e0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
329f0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
32a00 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
32a10 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
32a20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
32a30 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
32a40 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e  * Note that when
32a50 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
32a60 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72  s occur, pointer
32a70 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72  s returned by pr
32a80 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ior.** calls to 
32a90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32aa0 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63  lob(), sqlite3_c
32ab0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e  olumn_text(), an
32ac0 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d/or.** sqlite3_
32ad0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
32ae0 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74  may be invalidat
32af0 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76  ed..** Type conv
32b00 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e  ersions and poin
32b10 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e  ter invalidation
32b20 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
32b30 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   in the followin
32b40 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  g cases:.**.** <
32b50 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
32b60 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
32b70 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71  is a BLOB and sq
32b80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32b90 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  t() or.**      s
32ba0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
32bb0 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64  xt16() is called
32bc0 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  .  A zero-termin
32bd0 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20  ator might.**   
32be0 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64     need to be ad
32bf0 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e  ded to the strin
32c00 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  g.</li>.** <li> 
32c10 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
32c20 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78  ent is UTF-8 tex
32c30 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
32c40 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f  lumn_bytes16() o
32c50 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
32c60 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
32c70 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68  ) is called.  Th
32c80 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62  e content must b
32c90 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20  e converted.**  
32ca0 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f      to UTF-16.</
32cb0 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  li>.** <li> The 
32cc0 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20  initial content 
32cd0 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61  is UTF-16 text a
32ce0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
32cf0 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
32d00 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
32d10 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61  umn_text() is ca
32d20 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
32d30 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
32d40 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
32d50 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  UTF-8.</li>.** <
32d60 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76  /ul>.**.** ^Conv
32d70 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20  ersions between 
32d80 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46  UTF-16be and UTF
32d90 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73  -16le are always
32da0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61   done in place a
32db0 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76  nd do.** not inv
32dc0 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20  alidate a prior 
32dd0 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20  pointer, though 
32de0 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f  of course the co
32df0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66  ntent of the buf
32e00 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  fer.** that the 
32e10 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65  prior pointer re
32e20 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61  ferences will ha
32e30 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64  ve been modified
32e40 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a  .  Other kinds.*
32e50 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20  * of conversion 
32e60 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  are done in plac
32e70 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73  e when it is pos
32e80 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74  sible, but somet
32e90 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65  imes they.** are
32ea0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e   not possible an
32eb0 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73  d in those cases
32ec0 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20   prior pointers 
32ed0 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e  are invalidated.
32ee0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73  .**.** The safes
32ef0 74 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69  t policy is to i
32f00 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74  nvoke these rout
32f10 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f  ines.** in one o
32f20 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
32f30 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ways:.**.** <ul>
32f40 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
32f50 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66  _column_text() f
32f60 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
32f70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
32f80 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
32f90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
32fa0 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  ob() followed by
32fb0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32fc0 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
32fd0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
32fe0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c  umn_text16() fol
32ff0 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
33000 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
33010 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  )</li>.** </ul>.
33020 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
33030 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64  ords, you should
33040 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f   call sqlite3_co
33050 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20  lumn_text(),.** 
33060 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33070 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  lob(), or sqlite
33080 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
33090 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65  ) first to force
330a0 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69   the result.** i
330b0 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20  nto the desired 
330c0 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76  format, then inv
330d0 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  oke sqlite3_colu
330e0 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
330f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33100 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e  bytes16() to fin
33110 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  d the size of th
33120 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f  e result.  Do no
33130 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74  t mix calls.** t
33140 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
33150 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
33160 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
33170 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a   with calls to.*
33180 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
33190 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20  _bytes16(), and 
331a0 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  do not mix calls
331b0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
331c0 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77  mn_text16().** w
331d0 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  ith calls to sql
331e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
331f0 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s()..**.** ^The 
33200 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
33210 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69  d are valid unti
33220 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  l a type convers
33230 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a  ion occurs as.**
33240 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65   described above
33250 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69  , or until [sqli
33260 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
33270 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
33280 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
33290 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63  finalize()] is c
332a0 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d  alled.  ^The mem
332b0 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74  ory space used t
332c0 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a  o hold strings.*
332d0 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66  * and BLOBs is f
332e0 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c  reed automatical
332f0 6c 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c  ly.  Do <em>not<
33300 2f 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f  /em> pass the po
33310 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
33320 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
33330 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
33340 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
33350 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
33360 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
33370 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
33380 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
33390 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
333a0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
333b0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
333c0 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
333d0 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
333e0 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
333f0 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
33400 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
33410 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
33420 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
33430 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
33440 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
33450 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
33460 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
33470 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
33480 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
33490 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
334a0 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
334b0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
334c0 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
334d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
334e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
334f0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
33500 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f  _API int SQLITE_
33510 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
33520 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
33530 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33540 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
33550 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
33560 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
33570 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69  umn_bytes16(sqli
33580 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
33590 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
335a0 20 64 6f 75 62 6c 65 20 53 51 4c 49 54 45 5f 53   double SQLITE_S
335b0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
335c0 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
335d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
335e0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
335f0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
33600 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  CALL sqlite3_col
33610 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
33620 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
33630 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
33640 69 74 65 33 5f 69 6e 74 36 34 20 53 51 4c 49 54  ite3_int64 SQLIT
33650 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
33660 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
33670 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
33680 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
33690 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e  API const unsign
336a0 65 64 20 63 68 61 72 20 2a 53 51 4c 49 54 45 5f  ed char *SQLITE_
336b0 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
336c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69  column_text(sqli
336d0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
336e0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
336f0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c   const void *SQL
33700 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
33710 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
33720 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
33730 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
33740 54 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54  TE_API int SQLIT
33750 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
33760 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
33770 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
33780 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
33790 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  PI sqlite3_value
337a0 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c   *SQLITE_STDCALL
337b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
337c0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
337d0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
337e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
337f0 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61   Destroy A Prepa
33800 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62  red Statement Ob
33810 6a 65 63 74 0a 2a 2a 20 44 45 53 54 52 55 43 54  ject.** DESTRUCT
33820 4f 52 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OR: sqlite3_stmt
33830 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
33840 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
33850 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
33860 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
33870 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33880 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
33890 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
338a0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
338b0 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
338c0 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
338d0 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
338e0 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
338f0 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
33900 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
33910 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
33920 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
33930 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
33940 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
33950 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
33960 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
33970 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
33980 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
33990 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
339a0 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
339b0 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
339c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
339d0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
339e0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
339f0 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
33a00 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
33a10 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
33a20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33a30 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
33a40 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
33a50 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
33a60 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
33a70 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
33a80 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
33a90 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
33aa0 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
33ab0 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
33ac0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
33ad0 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
33ae0 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
33af0 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
33b00 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
33b10 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
33b20 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
33b30 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
33b40 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
33b50 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
33b60 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
33b70 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
33b80 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
33b90 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
33ba0 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
33bb0 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
33bc0 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
33bd0 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
33be0 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
33bf0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
33c00 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
33c10 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
33c20 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
33c30 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
33c40 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
33c50 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
33c60 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
33c70 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
33c80 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
33c90 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
33ca0 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
33cb0 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  uption..*/.SQLIT
33cc0 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
33cd0 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
33ce0 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
33cf0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
33d00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33d10 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
33d20 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
33d30 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ct.** METHOD: sq
33d40 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a  lite3_stmt.**.**
33d50 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
33d60 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
33d70 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
33d80 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
33d90 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
33da0 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
33db0 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
33dc0 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
33dd0 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
33de0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
33df0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
33e00 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
33e10 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
33e20 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
33e30 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
33e40 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
33e50 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
33e60 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
33e70 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
33e80 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
33e90 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
33ea0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
33eb0 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
33ec0 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
33ed0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33ee0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
33ef0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
33f00 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
33f10 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
33f20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
33f30 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
33f40 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
33f50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
33f60 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
33f70 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
33f80 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
33f90 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
33fa0 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
33fb0 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
33fc0 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
33fd0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33fe0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
33ff0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
34000 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
34010 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
34020 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
34030 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
34040 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
34050 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
34060 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
34070 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
34080 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
34090 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
340a0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
340b0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
340c0 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
340d0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
340e0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
340f0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
34100 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
34110 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
34120 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53  atement] S..*/.S
34130 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53 51  QLITE_API int SQ
34140 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
34150 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
34160 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
34170 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34180 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
34190 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
341a0 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
341b0 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
341c0 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
341d0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
341e0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
341f0 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
34200 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
34210 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
34220 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
34230 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
34240 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
34250 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
34260 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
34270 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
34280 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
34290 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
342a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
342b0 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
342c0 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
342d0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
342e0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
342f0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
34300 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
34310 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
34320 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
34330 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
34340 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
34350 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
34360 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
34370 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
34380 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
34390 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
343a0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
343b0 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
343c0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
343d0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
343e0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
343f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
34400 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
34410 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
34420 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
34430 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
34440 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
34450 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
34460 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
34470 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
34480 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
34490 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
344a0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
344b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
344c0 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
344d0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
344e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
344f0 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
34500 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
34510 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
34520 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
34530 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
34540 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
34550 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
34560 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
34570 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
34580 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
34590 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
345a0 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
345b0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
345c0 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
345d0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
345e0 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
345f0 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
34600 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
34610 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
34620 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
34630 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
34640 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
34650 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
34660 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
34670 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
34680 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
34690 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
346a0 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
346b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
346c0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
346d0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
346e0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
346f0 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
34700 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
34710 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
34720 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
34730 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
34740 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
34750 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
34760 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
34770 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
34780 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
34790 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
347a0 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
347b0 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
347c0 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
347d0 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
347e0 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
347f0 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
34800 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
34810 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
34820 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
34830 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
34840 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
34850 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
34860 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
34870 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
34880 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
34890 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
348a0 6e 20 73 68 6f 75 6c 64 20 73 65 74 20 74 68 69  n should set thi
348b0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  s parameter to.*
348c0 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  * [SQLITE_UTF16L
348d0 45 5d 20 69 66 20 74 68 65 20 66 75 6e 63 74 69  E] if the functi
348e0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
348f0 6e 20 69 6e 76 6f 6b 65 73 20 0a 2a 2a 20 5b 73  n invokes .** [s
34900 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34910 74 31 36 6c 65 28 29 5d 20 6f 6e 20 61 6e 20 69  t16le()] on an i
34920 6e 70 75 74 2c 20 6f 72 20 5b 53 51 4c 49 54 45  nput, or [SQLITE
34930 5f 55 54 46 31 36 42 45 5d 20 69 66 20 74 68 65  _UTF16BE] if the
34940 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
34950 6f 6e 20 69 6e 76 6f 6b 65 73 20 5b 73 71 6c 69  on invokes [sqli
34960 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
34970 62 65 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75  be()] on an inpu
34980 74 2c 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  t, or.** [SQLITE
34990 5f 55 54 46 31 36 5d 20 69 66 20 5b 73 71 6c 69  _UTF16] if [sqli
349a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
349b0 28 29 5d 20 69 73 20 75 73 65 64 2c 20 6f 72 20  ()] is used, or 
349c0 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 0a 2a 2a  [SQLITE_UTF8].**
349d0 20 6f 74 68 65 72 77 69 73 65 2e 20 20 5e 54 68   otherwise.  ^Th
349e0 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
349f0 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
34a00 74 65 72 65 64 20 6d 75 6c 74 69 70 6c 65 20 74  tered multiple t
34a10 69 6d 65 73 20 75 73 69 6e 67 0a 2a 2a 20 64 69  imes using.** di
34a20 66 66 65 72 65 6e 74 20 70 72 65 66 65 72 72 65  fferent preferre
34a30 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
34a40 2c 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74  , with different
34a50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
34a60 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 65 6e 63   for.** each enc
34a70 6f 64 69 6e 67 2e 0a 2a 2a 20 5e 57 68 65 6e 20  oding..** ^When 
34a80 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
34a90 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
34aa0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
34ab0 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
34ac0 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
34ad0 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
34ae0 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
34af0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
34b00 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
34b10 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
34b20 72 61 6d 65 74 65 72 20 6d 61 79 20 6f 70 74 69  rameter may opti
34b30 6f 6e 61 6c 6c 79 20 62 65 20 4f 52 65 64 20 77  onally be ORed w
34b40 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 54 45  ith [SQLITE_DETE
34b50 52 4d 49 4e 49 53 54 49 43 5d 0a 2a 2a 20 74 6f  RMINISTIC].** to
34b60 20 73 69 67 6e 61 6c 20 74 68 61 74 20 74 68 65   signal that the
34b70 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 61   function will a
34b80 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
34b90 20 73 61 6d 65 20 72 65 73 75 6c 74 20 67 69 76   same result giv
34ba0 65 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 69  en.** the same i
34bb0 6e 70 75 74 73 20 77 69 74 68 69 6e 20 61 20 73  nputs within a s
34bc0 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d  ingle SQL statem
34bd0 65 6e 74 2e 20 20 4d 6f 73 74 20 53 51 4c 20 66  ent.  Most SQL f
34be0 75 6e 63 74 69 6f 6e 73 20 61 72 65 0a 2a 2a 20  unctions are.** 
34bf0 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
34c00 54 68 65 20 62 75 69 6c 74 2d 69 6e 20 5b 72 61  The built-in [ra
34c10 6e 64 6f 6d 28 29 5d 20 53 51 4c 20 66 75 6e 63  ndom()] SQL func
34c20 74 69 6f 6e 20 69 73 20 61 6e 20 65 78 61 6d 70  tion is an examp
34c30 6c 65 20 6f 66 20 61 0a 2a 2a 20 66 75 6e 63 74  le of a.** funct
34c40 69 6f 6e 20 74 68 61 74 20 69 73 20 6e 6f 74 20  ion that is not 
34c50 64 65 74 65 72 6d 69 6e 69 73 74 69 63 2e 20 20  deterministic.  
34c60 54 68 65 20 53 51 4c 69 74 65 20 71 75 65 72 79  The SQLite query
34c70 20 70 6c 61 6e 6e 65 72 20 69 73 20 61 62 6c 65   planner is able
34c80 20 74 6f 0a 2a 2a 20 70 65 72 66 6f 72 6d 20 61   to.** perform a
34c90 64 64 69 74 69 6f 6e 61 6c 20 6f 70 74 69 6d 69  dditional optimi
34ca0 7a 61 74 69 6f 6e 73 20 6f 6e 20 64 65 74 65 72  zations on deter
34cb0 6d 69 6e 69 73 74 69 63 20 66 75 6e 63 74 69 6f  ministic functio
34cc0 6e 73 2c 20 73 6f 20 75 73 65 0a 2a 2a 20 6f 66  ns, so use.** of
34cd0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 44 45 54   the [SQLITE_DET
34ce0 45 52 4d 49 4e 49 53 54 49 43 5d 20 66 6c 61 67  ERMINISTIC] flag
34cf0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
34d00 77 68 65 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a  where possible..
34d10 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74  **.** ^(The fift
34d20 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
34d30 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
34d40 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
34d50 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
34d60 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
34d70 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
34d80 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
34d90 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
34da0 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  data()].)^.**.**
34db0 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76   ^The sixth, sev
34dc0 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20  enth and eighth 
34dd0 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
34de0 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
34df0 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
34e00 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
34e10 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
34e20 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
34e30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
34e40 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
34e50 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
34e60 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
34e70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34e80 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
34e90 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e  callback only; N
34ea0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73  ULL pointers mus
34eb0 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
34ec0 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
34ed0 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
34ee0 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65  s. ^An aggregate
34ef0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
34f00 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
34f10 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
34f20 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
34f30 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  and NULL pointer
34f40 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
34f50 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
34f60 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
34f70 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
34f80 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
34f90 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  pass NULL pointe
34fa0 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  rs for all three
34fb0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
34fc0 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lbacks..**.** ^(
34fd0 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72  If the ninth par
34fe0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
34ff0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35000 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55  n_v2() is not NU
35010 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  LL,.** then it i
35020 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  s destructor for
35030 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
35040 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a   data pointer. .
35050 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  ** The destructo
35060 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  r is invoked whe
35070 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  n the function i
35080 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65  s deleted, eithe
35090 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76  r by being.** ov
350a0 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e  erloaded or when
350b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
350c0 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
350d0 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72  )^.** ^The destr
350e0 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e  uctor is also in
350f0 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
35100 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
35110 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
35120 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e  v2() fails..** ^
35130 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63  When the destruc
35140 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  tor callback of 
35150 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
35160 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
35170 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
35180 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
35190 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
351a0 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  y of the applica
351b0 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f  tion data .** po
351c0 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
351d0 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  the fifth parame
351e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
351f0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
35200 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  2()..**.** ^It i
35210 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
35220 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
35230 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
35240 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
35250 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
35260 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
35270 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
35280 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
35290 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
352a0 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
352b0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
352c0 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
352d0 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
352e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
352f0 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
35300 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
35310 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
35320 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
35330 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
35340 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
35350 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
35360 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
35370 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
35380 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
35390 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
353a0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
353b0 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
353c0 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
353d0 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
353e0 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
353f0 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
35400 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
35410 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
35420 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
35430 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
35440 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
35450 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
35460 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
35470 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
35480 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
35490 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
354a0 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
354b0 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
354c0 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
354d0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
354e0 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
354f0 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
35500 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
35510 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
35520 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
35530 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
35540 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35550 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nctions..**.** ^
35560 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
35570 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
35580 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
35590 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
355a0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
355b0 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
355c0 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
355d0 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
355e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
355f0 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
35600 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
35610 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
35620 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
35630 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
35640 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
35650 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43 41  int SQLITE_STDCA
35660 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  LL sqlite3_creat
35670 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71  e_function(.  sq
35680 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
35690 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
356a0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
356b0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
356c0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
356d0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
356e0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
356f0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
35700 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
35710 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
35720 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
35730 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
35740 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
35750 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35760 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
35770 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44 43   int SQLITE_STDC
35780 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63 72 65 61  ALL sqlite3_crea
35790 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
357a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
357b0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
357c0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
357d0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
357e0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
357f0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
35800 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
35810 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
35820 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
35830 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
35840 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
35850 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
35860 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
35870 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
35880 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  ext*).);.SQLITE_
35890 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53  API int SQLITE_S
358a0 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 63  TDCALL sqlite3_c
358b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
358c0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
358d0 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
358e0 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
358f0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
35900 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
35910 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
35920 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
35930 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
35940 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
35950 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
35960 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35970 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
35980 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
35990 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
359a0 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
359b0 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
359c0 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
359d0 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
359e0 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
359f0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
35a00 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
35a10 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
35a20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
35a30 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
35a40 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
35a50 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
35a60 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
35a70 20 20 20 20 31 20 20 20 20 2f 2a 20 49 4d 50 3a      1    /* IMP:
35a80 20 52 2d 33 37 35 31 34 2d 33 35 35 36 36 20 2a   R-37514-35566 *
35a90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
35aa0 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
35ab0 32 20 20 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 30  2    /* IMP: R-0
35ac0 33 33 37 31 2d 33 37 36 33 37 20 2a 2f 0a 23 64  3371-37637 */.#d
35ad0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
35ae0 31 36 42 45 20 20 20 20 20 20 20 20 33 20 20 20  16BE        3   
35af0 20 2f 2a 20 49 4d 50 3a 20 52 2d 35 31 39 37 31   /* IMP: R-51971
35b00 2d 33 34 31 35 34 20 2a 2f 0a 23 64 65 66 69 6e  -34154 */.#defin
35b10 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
35b20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
35b30 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
35b40 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
35b50 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
35b60 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 44         5    /* D
35b70 65 70 72 65 63 61 74 65 64 20 2a 2f 0a 23 64 65  eprecated */.#de
35b80 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
35b90 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20  6_ALIGNED  8    
35ba0 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  /* sqlite3_creat
35bb0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79  e_collation only
35bc0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
35bd0 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 46 6c  REF: Function Fl
35be0 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ags.**.** These 
35bf0 63 6f 6e 73 74 61 6e 74 73 20 6d 61 79 20 62 65  constants may be
35c00 20 4f 52 65 64 20 74 6f 67 65 74 68 65 72 20 77   ORed together w
35c10 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
35c20 49 54 45 5f 55 54 46 38 20 7c 20 70 72 65 66 65  ITE_UTF8 | prefe
35c30 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
35c40 6e 67 5d 20 61 73 20 74 68 65 20 66 6f 75 72 74  ng] as the fourt
35c50 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  h argument.** to
35c60 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
35c70 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 5b 73  _function()], [s
35c80 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35c90 6e 63 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  nction16()], or.
35ca0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
35cb0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
35cc0 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
35cd0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
35ce0 49 43 20 20 20 20 30 78 38 30 30 0a 0a 2f 2a 0a  IC    0x800../*.
35cf0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70  ** CAPI3REF: Dep
35d00 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e  recated Function
35d10 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a  s.** DEPRECATED.
35d20 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
35d30 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65  tions are [depre
35d40 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65  cated].  In orde
35d50 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a  r to maintain.**
35d60 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
35d70 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c  tibility with ol
35d80 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20  der code, these 
35d90 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e  functions contin
35da0 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70  ue .** to be sup
35db0 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72  ported.  However
35dc0 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  , new applicatio
35dd0 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a  ns should avoid.
35de0 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  ** the use of th
35df0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
35e00 54 6f 20 65 6e 63 6f 75 72 61 67 65 20 70 72 6f  To encourage pro
35e10 67 72 61 6d 6d 65 72 73 20 74 6f 20 61 76 6f 69  grammers to avoi
35e20 64 0a 2a 2a 20 74 68 65 73 65 20 66 75 6e 63 74  d.** these funct
35e30 69 6f 6e 73 2c 20 77 65 20 77 69 6c 6c 20 6e 6f  ions, we will no
35e40 74 20 65 78 70 6c 61 69 6e 20 77 68 61 74 20 74  t explain what t
35e50 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
35e60 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
35e70 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
35e80 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
35e90 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49 54  ECATED int SQLIT
35ea0 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
35eb0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e  3_aggregate_coun
35ec0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
35ed0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
35ee0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
35ef0 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  D int SQLITE_STD
35f00 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 65 78 70  CALL sqlite3_exp
35f10 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
35f20 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
35f30 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
35f40 44 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  D int SQLITE_STD
35f50 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 74 72 61  CALL sqlite3_tra
35f60 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73  nsfer_bindings(s
35f70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71  qlite3_stmt*, sq
35f80 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51  lite3_stmt*);.SQ
35f90 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
35fa0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 53  DEPRECATED int S
35fb0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
35fc0 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
35fd0 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
35fe0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
35ff0 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 53 51  PRECATED void SQ
36000 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c  LITE_STDCALL sql
36010 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
36020 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
36030 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
36040 52 45 43 41 54 45 44 20 69 6e 74 20 53 51 4c 49  RECATED int SQLI
36050 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74  TE_STDCALL sqlit
36060 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28  e3_memory_alarm(
36070 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
36080 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29  lite3_int64,int)
36090 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
360a0 20 20 20 20 20 20 20 20 76 6f 69 64 2a 2c 73 71          void*,sq
360b0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
360c0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
360d0 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
360e0 53 51 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45  SQL Values.** ME
360f0 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61  THOD: sqlite3_va
36100 6c 75 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  lue.**.** The C-
36110 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
36120 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
36130 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
36140 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
36150 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
36160 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
36170 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
36180 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
36190 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
361a0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 20 20   or aggregate.  
361b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63  .**.** The xFunc
361c0 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e   (for scalar fun
361d0 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70  ctions) or xStep
361e0 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73   (for aggregates
361f0 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  ) parameters.** 
36200 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  to [sqlite3_crea
36210 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
36220 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
36230 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
36240 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62  .** define callb
36250 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  acks that implem
36260 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
36270 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
36280 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64  ates..** The 3rd
36290 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
362a0 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73  ese callbacks is
362b0 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
362c0 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f  nters to.** [pro
362d0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
362e0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20  alue] objects.  
362f0 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71  There is one [sq
36300 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
36310 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20  ect for.** each 
36320 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
36330 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20   SQL function.  
36340 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
36350 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78  re used to.** ex
36360 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f  tract values fro
36370 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
36380 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  alue] objects..*
36390 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
363a0 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69  nes work only wi
363b0 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  th [protected sq
363c0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
363d0 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  ects..** Any att
363e0 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73  empt to use thes
363f0 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e  e routines on an
36400 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
36410 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
36420 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69  object results i
36430 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61  n undefined beha
36440 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  vior..**.** ^The
36450 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
36460 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63   just like the c
36470 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f  orresponding [co
36480 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
36490 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74  tions].** except
364a0 20 74 68 61 74 20 74 68 65 73 65 20 72 6f 75 74   that these rout
364b0 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
364c0 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
364d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
364e0 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
364f0 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
36500 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
36510 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
36520 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
36530 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36540 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
36550 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
36560 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
36570 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
36580 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
36590 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
365a0 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
365b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
365c0 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
365d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
365e0 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
365f0 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
36600 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
36610 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
36620 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
36630 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
36640 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
36650 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
36660 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
36670 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
36680 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
36690 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
366a0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
366b0 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
366c0 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
366d0 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
366e0 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
366f0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
36700 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
36710 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
36720 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
36730 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
36740 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
36750 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
36760 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
36770 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
36780 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
36790 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
367a0 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
367b0 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
367c0 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
367d0 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
367e0 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
367f0 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
36800 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
36810 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
36820 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
36830 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
36840 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
36850 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
36860 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
36870 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
36880 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
36890 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
368a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
368b0 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
368c0 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
368d0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
368e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
368f0 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
36900 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
36910 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
36920 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
36930 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
36940 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
36950 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
36960 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
36970 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
36980 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
36990 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
369a0 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
369b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
369c0 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51  arameters..*/.SQ
369d0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
369e0 6f 69 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  oid *SQLITE_STDC
369f0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
36a00 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76  e_blob(sqlite3_v
36a10 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
36a20 50 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54  PI int SQLITE_ST
36a30 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61  DCALL sqlite3_va
36a40 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
36a50 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
36a60 45 5f 41 50 49 20 69 6e 74 20 53 51 4c 49 54 45  E_API int SQLITE
36a70 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
36a80 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73  _value_bytes16(s
36a90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36aa0 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c  SQLITE_API doubl
36ab0 65 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c  e SQLITE_STDCALL
36ac0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64   sqlite3_value_d
36ad0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  ouble(sqlite3_va
36ae0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
36af0 49 20 69 6e 74 20 53 51 4c 49 54 45 5f 53 54 44  I int SQLITE_STD
36b00 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c  CALL sqlite3_val
36b10 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
36b20 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
36b30 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
36b40 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
36b50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
36b60 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
36b70 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
36b80 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63  const unsigned c
36b90 68 61 72 20 2a 53 51 4c 49 54 45 5f 53 54 44 43  har *SQLITE_STDC
36ba0 41 4c 4c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ALL sqlite3_valu
36bb0 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
36bc0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
36bd0 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 53  PI const void *S
36be0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
36bf0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
36c00 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
36c10 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
36c20 6f 6e 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54  onst void *SQLIT
36c30 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
36c40 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
36c50 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36c60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
36c70 73 74 20 76 6f 69 64 20 2a 53 51 4c 49 54 45 5f  st void *SQLITE_
36c80 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33 5f  STDCALL sqlite3_
36c90 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
36ca0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
36cb0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 53  SQLITE_API int S
36cc0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
36cd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65  lite3_value_type
36ce0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
36cf0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
36d00 20 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20   SQLITE_STDCALL 
36d10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
36d20 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
36d30 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
36d40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 70  ** CAPI3REF: Cop
36d50 79 20 41 6e 64 20 46 72 65 65 20 53 51 4c 20 56  y And Free SQL V
36d60 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  alues.** METHOD:
36d70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a   sqlite3_value.*
36d80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36d90 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69  3_value_dup(V) i
36da0 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61  nterface makes a
36db0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71   copy of the [sq
36dc0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20  lite3_value].** 
36dd0 6f 62 6a 65 63 74 20 44 20 61 6e 64 20 72 65 74  object D and ret
36de0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
36df0 6f 20 74 68 61 74 20 63 6f 70 79 2e 20 20 5e 54  o that copy.  ^T
36e00 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
36e10 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  e] returned.** i
36e20 73 20 61 20 5b 70 72 6f 74 65 63 74 65 64 20 73  s a [protected s
36e30 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
36e40 6a 65 63 74 20 65 76 65 6e 20 69 66 20 74 68 65  ject even if the
36e50 20 69 6e 70 75 74 20 69 73 20 6e 6f 74 2e 0a 2a   input is not..*
36e60 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
36e70 61 6c 75 65 5f 64 75 70 28 56 29 20 69 6e 74 65  alue_dup(V) inte
36e80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55  rface returns NU
36e90 4c 4c 20 69 66 20 56 20 69 73 20 4e 55 4c 4c 20  LL if V is NULL 
36ea0 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72  or if a.** memor
36eb0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
36ec0 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ls..**.** ^The s
36ed0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66 72 65  qlite3_value_fre
36ee0 65 28 56 29 20 69 6e 74 65 72 66 61 63 65 20 66  e(V) interface f
36ef0 72 65 65 73 20 61 6e 20 5b 73 71 6c 69 74 65 33  rees an [sqlite3
36f00 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
36f10 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
36f20 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
36f30 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 29 5d  te3_value_dup()]
36f40 2e 20 20 5e 49 66 20 56 20 69 73 20 61 20 4e 55  .  ^If V is a NU
36f50 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68  LL pointer.** th
36f60 65 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  en sqlite3_value
36f70 5f 66 72 65 65 28 56 29 20 69 73 20 61 20 68 61  _free(V) is a ha
36f80 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f  rmless no-op..*/
36f90 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
36fa0 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
36fb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 53  sqlite3_value *S
36fc0 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71  QLITE_STDCALL sq
36fd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28  lite3_value_dup(
36fe0 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
36ff0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
37000 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  I SQLITE_EXPERIM
37010 45 4e 54 41 4c 20 76 6f 69 64 20 53 51 4c 49 54  ENTAL void SQLIT
37020 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65  E_STDCALL sqlite
37030 33 5f 76 61 6c 75 65 5f 66 72 65 65 28 73 71 6c  3_value_free(sql
37040 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
37050 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
37060 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
37070 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
37080 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
37090 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
370a0 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
370b0 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
370c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
370d0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
370e0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
370f0 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
37100 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
37110 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
37120 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
37130 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
37140 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
37150 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
37160 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
37170 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
37180 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
37190 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
371a0 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
371b0 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
371c0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
371d0 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
371e0 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
371f0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
37200 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
37210 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
37220 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
37230 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
37240 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
37250 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
37260 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
37270 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
37280 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
37290 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
372a0 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
372b0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
372c0 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
372d0 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
372e0 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
372f0 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
37300 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
37310 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
37320 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
37330 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
37340 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
37350 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
37360 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
37370 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
37380 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
37390 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
373a0 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
373b0 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
373c0 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
373d0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
373e0 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
373f0 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
37400 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
37410 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
37420 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
37430 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
37440 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
37450 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
37460 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20  ULL pointer .** 
37470 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65  when first calle
37480 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74  d if N is less t
37490 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
374a0 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d  zero or if a mem
374b0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20  ory.** allocate 
374c0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
374d0 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
374e0 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
374f0 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
37500 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
37510 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
37520 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
37530 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
37540 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
37550 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
37560 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
37570 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
37580 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
37590 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
375a0 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
375b0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
375c0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
375d0 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
375e0 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
375f0 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69  llocation.)^  Wi
37600 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  thin the xFinal 
37610 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20  callback, it is 
37620 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74  customary to set
37630 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73  .** N=0 in calls
37640 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
37650 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
37660 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a  N) so that no .*
37670 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f  * pointless memo
37680 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f  ry allocations o
37690 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ccur..**.** ^SQL
376a0 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
376b0 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
376c0 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
376d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
376e0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
376f0 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
37700 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
37710 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
37720 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
37730 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
37740 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
37750 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
37760 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
37770 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
37780 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
37790 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
377a0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
377b0 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
377c0 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
377d0 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
377e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
377f0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
37800 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
37810 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
37820 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
37830 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
37840 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
37850 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
37860 53 51 4c 49 54 45 5f 53 54 44 43 41 4c 4c 20 73  SQLITE_STDCALL s
37870 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
37880 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33  _context(sqlite3
37890 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
378a0 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Bytes);../*.** C
378b0 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61  API3REF: User Da
378c0 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  ta For Functions
378d0 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
378e0 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
378f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75  * ^The sqlite3_u
37900 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72  ser_data() inter
37910 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
37920 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
37930 69 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74  inter that was t
37940 68 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72  he pUserData par
37950 61 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20  ameter (the 5th 
37960 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
37970 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
37980 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
37990 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
379a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
379b0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
379c0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
379d0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
379e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
379f0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
37a00 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
37a10 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
37a20 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
37a30 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
37a40 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
37a50 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
37a60 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
37a70 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
37a80 64 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  d *SQLITE_STDCAL
37a90 4c 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  L sqlite3_user_d
37aa0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
37ab0 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
37ac0 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
37ad0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
37ae0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45 54  Functions.** MET
37af0 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  HOD: sqlite3_con
37b00 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  text.**.** ^The 
37b10 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
37b20 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
37b30 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
37b40 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
37b50 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
37b60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
37b70 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
37b80 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
37b90 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
37ba0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
37bb0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
37bc0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
37bd0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
37be0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
37bf0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
37c00 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
37c10 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53  d function..*/.S
37c20 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
37c30 33 20 2a 53 51 4c 49 54 45 5f 53 54 44 43 41 4c  3 *SQLITE_STDCAL
37c40 4c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  L sqlite3_contex
37c50 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
37c60 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
37c70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
37c80 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
37c90 72 79 20 44 61 74 61 0a 2a 2a 20 4d 45 54 48 4f  ry Data.** METHO
37ca0 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
37cb0 78 74 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66  xt.**.** These f
37cc0 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
37cd0 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67  used by (non-agg
37ce0 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63  regate) SQL func
37cf0 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f  tions to.** asso
37d00 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77  ciate metadata w
37d10 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c  ith argument val
37d20 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65  ues. If the same
37d30 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64   value is passed
37d40 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20   to.** multiple 
37d50 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
37d60 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63  he same SQL func
37d70 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72  tion during quer
37d80 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64  y execution, und
37d90 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75  er.** some circu
37da0 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73  mstances the ass
37db0 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61  ociated metadata
37dc0 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65   may be preserve
37dd0 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a  d.  An example.*
37de0 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73 20  * of where this 
37df0 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c 20  might be useful 
37e00 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d  is in a regular-
37e10 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68  expression match
37e20 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  ing.** function.
37e30 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
37e40 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
37e50 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
37e60 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73  can be stored as
37e70 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73  .** metadata ass
37e80 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
37e90 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e   pattern string.
37ea0 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f    .** Then as lo
37eb0 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65 72  ng as the patter
37ec0 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73  n string remains
37ed0 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68   the same,.** th
37ee0 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
37ef0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
37f00 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
37f10 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
37f20 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
37f30 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  me function..**.
37f40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37f50 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
37f60 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37f70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
37f80 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
37f90 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
37fa0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
37fb0 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
37fc0 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
37fd0 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
37fe0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
37ff0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
38000 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e  . ^If there is n
38010 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  o metadata.** as
38020 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
38030 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d  e function argum
38040 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65  ent, this sqlite
38050 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
38060 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74  interface.** ret
38070 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
38080 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
38090 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
380a0 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74  ata(C,N,P,X) int
380b0 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20 61  erface saves P a
380c0 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74  s metadata for t
380d0 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
380e0 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
380f0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
38100 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65  unction.  ^Subse
38110 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
38120 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
38130 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72  xdata(C,N) retur
38140 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73  n P from the mos
38150 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69  t recent.** sqli
38160 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
38170 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66  C,N,P,X) call if
38180 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
38190 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a   still valid or.
381a0 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d  ** NULL if the m
381b0 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
381c0 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e   discarded..** ^
381d0 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20  After each call 
381e0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
381f0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
38200 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e  where X is not N
38210 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ULL,.** SQLite w
38220 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
38230 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
38240 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d 65  on X with parame
38250 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a  ter P exactly.**
38260 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20   once, when the 
38270 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73 63  metadata is disc
38280 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65  arded..** SQLite
38290 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73 63   is free to disc
382a0 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74 61  ard the metadata
382b0 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e   at any time, in
382c0 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a  cluding: <ul>.**
382d0 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63   <li> when the c
382e0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
382f0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
38300 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c  changes, or.** <
38310 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  li> when [sqlite
38320 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
38330 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
38340 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72  )] is called for
38350 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c   the.**      SQL
38360 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a   statement, or.*
38370 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69  * <li> when sqli
38380 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
38390 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61  ) is invoked aga
383a0 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70  in on the same p
383b0 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20  arameter, or.** 
383c0 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20  <li> during the 
383d0 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33  original sqlite3
383e0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 63  _set_auxdata() c
383f0 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72  all when a memor
38400 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63  y .**      alloc
38410 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
38420 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  rs. </ul>)^.**.*
38430 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20  * Note the last 
38440 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63  bullet in partic
38450 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74 72  ular.  The destr
38460 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73  uctor X in .** s
38470 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
38480 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68  ta(C,N,P,X) migh
38490 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65  t be called imme
384a0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20  diately, before 
384b0 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  the.** sqlite3_s
384c0 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74  et_auxdata() int
384d0 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74 75  erface even retu
384e0 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69  rns.  Hence sqli
384f0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
38500 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63  ).** should be c
38510 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65  alled near the e
38520 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nd of the functi
38530 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
38540 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e  n and the.** fun
38550 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
38560 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20  tion should not 
38570 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20  make any use of 
38580 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74  P after.** sqlit
38590 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
385a0 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
385b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61  ..**.** ^(In pra
385c0 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20  ctice, metadata 
385d0 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74  is preserved bet
385e0 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61  ween function ca
385f0 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74  lls for.** funct
38600 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ion parameters t
38610 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d  hat are compile-
38620 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20  time constants, 
38630 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61  including litera
38640 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
38650 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64  [parameters] and
38660 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d   expressions com
38670 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73  posed from the s
38680 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ame.)^.**.** The
38690 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
386a0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
386b0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
386c0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
386d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
386e0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
386f0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 53 51 4c  TE_API void *SQL
38700 49 54 45 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69  ITE_STDCALL sqli
38710 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
38720 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
38730 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45  , int N);.SQLITE
38740 5f 41 50 49 20 76 6f 69 64 20 53 51 4c 49 54 45  _API void SQLITE
38750 5f 53 54 44 43 41 4c 4c 20 73 71 6c 69 74 65 33  _STDCALL sqlite3
38760 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
38770 69 74