/ Hex Artifact Content
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Artifact 1971ab9709e010d52a02a1a6276d5a2f9b947476:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 64 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a  ed to operate..*
04e0: 2a 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66  *.** The name of
04f0: 20 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72   this file under
0500: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d   configuration m
0510: 61 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71  anagement is "sq
0520: 6c 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54  lite.h.in"..** T
0530: 68 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65  he makefile make
0540: 73 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61  s some minor cha
0550: 6e 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c  nges to this fil
0560: 65 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72  e (such as inser
0570: 74 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73  ting.** the vers
0580: 69 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20  ion number) and 
0590: 63 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65  changes its name
05a0: 20 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20   to "sqlite3.h" 
05b0: 61 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68  as.** part of th
05c0: 65 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e  e build process.
05d0: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
05e0: 54 45 33 5f 48 0a 23 64 65 66 69 6e 65 20 53 51  TE3_H.#define SQ
05f0: 4c 49 54 45 33 5f 48 0a 23 69 6e 63 6c 75 64 65  LITE3_H.#include
0600: 20 3c 73 74 64 61 72 67 2e 68 3e 20 20 20 20 20   <stdarg.h>     
0610: 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72 20 74 68  /* Needed for th
0620: 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 66 20  e definition of 
0630: 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a  va_list */../*.*
0640: 2a 20 4d 61 6b 65 20 73 75 72 65 20 77 65 20 63  * Make sure we c
0650: 61 6e 20 63 61 6c 6c 20 74 68 69 73 20 73 74 75  an call this stu
0660: 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a  ff from C++..*/.
0670: 23 69 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c  #ifdef __cpluspl
0680: 75 73 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a  us.extern "C" {.
0690: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 50  #endif.../*.** P
06a0: 72 6f 76 69 64 65 20 74 68 65 20 61 62 69 6c 69  rovide the abili
06b0: 74 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 6c  ty to override l
06c0: 69 6e 6b 61 67 65 20 66 65 61 74 75 72 65 73 20  inkage features 
06d0: 6f 66 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  of the interface
06e0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
06f0: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
0700: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
0710: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
0720: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0730: 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  PI.# define SQLI
0740: 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 23 69  TE_API.#endif.#i
0750: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 43 44 45  fndef SQLITE_CDE
0760: 43 4c 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CL.# define SQLI
0770: 54 45 5f 43 44 45 43 4c 0a 23 65 6e 64 69 66 0a  TE_CDECL.#endif.
0780: 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41  #ifndef SQLITE_A
0790: 50 49 43 41 4c 4c 0a 23 20 64 65 66 69 6e 65 20  PICALL.# define 
07a0: 53 51 4c 49 54 45 5f 41 50 49 43 41 4c 4c 0a 23  SQLITE_APICALL.#
07b0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
07c0: 4c 49 54 45 5f 53 54 44 43 41 4c 4c 0a 23 20 64  LITE_STDCALL.# d
07d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 44  efine SQLITE_STD
07e0: 43 41 4c 4c 20 53 51 4c 49 54 45 5f 41 50 49 43  CALL SQLITE_APIC
07f0: 41 4c 4c 0a 23 65 6e 64 69 66 0a 23 69 66 6e 64  ALL.#endif.#ifnd
0800: 65 66 20 53 51 4c 49 54 45 5f 43 41 4c 4c 42 41  ef SQLITE_CALLBA
0810: 43 4b 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  CK.# define SQLI
0820: 54 45 5f 43 41 4c 4c 42 41 43 4b 0a 23 65 6e 64  TE_CALLBACK.#end
0830: 69 66 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  if.#ifndef SQLIT
0840: 45 5f 53 59 53 41 50 49 0a 23 20 64 65 66 69 6e  E_SYSAPI.# defin
0850: 65 20 53 51 4c 49 54 45 5f 53 59 53 41 50 49 0a  e SQLITE_SYSAPI.
0860: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
0870: 65 73 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73  ese no-op macros
0880: 20 61 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f   are used in fro
0890: 6e 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73  nt of interfaces
08a0: 20 74 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a   to mark those.*
08b0: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 73 20  * interfaces as 
08c0: 65 69 74 68 65 72 20 64 65 70 72 65 63 61 74 65  either deprecate
08d0: 64 20 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61  d or experimenta
08e0: 6c 2e 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74  l.  New applicat
08f0: 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  ions.** should n
0900: 6f 74 20 75 73 65 20 64 65 70 72 65 63 61 74 65  ot use deprecate
0910: 64 20 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74  d interfaces - t
0920: 68 65 79 20 61 72 65 20 73 75 70 70 6f 72 74 65  hey are supporte
0930: 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 0a  d for backwards.
0940: 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ** compatibility
0950: 20 6f 6e 6c 79 2e 20 20 41 70 70 6c 69 63 61 74   only.  Applicat
0960: 69 6f 6e 20 77 72 69 74 65 72 73 20 73 68 6f 75  ion writers shou
0970: 6c 64 20 62 65 20 61 77 61 72 65 20 74 68 61 74  ld be aware that
0980: 0a 2a 2a 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  .** experimental
0990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
09a0: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
09b0: 65 20 69 6e 20 70 6f 69 6e 74 20 72 65 6c 65 61  e in point relea
09c0: 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ses..**.** These
09d0: 20 6d 61 63 72 6f 73 20 75 73 65 64 20 74 6f 20   macros used to 
09e0: 72 65 73 6f 6c 76 65 20 74 6f 20 76 61 72 69 6f  resolve to vario
09f0: 75 73 20 6b 69 6e 64 73 20 6f 66 20 63 6f 6d 70  us kinds of comp
0a00: 69 6c 65 72 20 6d 61 67 69 63 20 74 68 61 74 0a  iler magic that.
0a10: 2a 2a 20 77 6f 75 6c 64 20 67 65 6e 65 72 61 74  ** would generat
0a20: 65 20 77 61 72 6e 69 6e 67 20 6d 65 73 73 61 67  e warning messag
0a30: 65 73 20 77 68 65 6e 20 74 68 65 79 20 77 65 72  es when they wer
0a40: 65 20 75 73 65 64 2e 20 20 42 75 74 20 74 68 61  e used.  But tha
0a50: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 20 6d 61  t.** compiler ma
0a60: 67 69 63 20 65 6e 64 65 64 20 75 70 20 67 65 6e  gic ended up gen
0a70: 65 72 61 74 69 6e 67 20 73 75 63 68 20 61 20 66  erating such a f
0a80: 6c 75 72 72 79 20 6f 66 20 62 75 67 20 72 65 70  lurry of bug rep
0a90: 6f 72 74 73 0a 2a 2a 20 74 68 61 74 20 77 65 20  orts.** that we 
0aa0: 68 61 76 65 20 74 61 6b 65 6e 20 69 74 20 61 6c  have taken it al
0ab0: 6c 20 6f 75 74 20 61 6e 64 20 67 6f 6e 65 20 62  l out and gone b
0ac0: 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 73 69 6d  ack to using sim
0ad0: 70 6c 65 0a 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72  ple.** noop macr
0ae0: 6f 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  os..*/.#define S
0af0: 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
0b00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0b10: 45 58 50 45 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a  EXPERIMENTAL../*
0b20: 0a 2a 2a 20 45 6e 73 75 72 65 20 74 68 65 73 65  .** Ensure these
0b30: 20 73 79 6d 62 6f 6c 73 20 77 65 72 65 20 6e 6f   symbols were no
0b40: 74 20 64 65 66 69 6e 65 64 20 62 79 20 73 6f 6d  t defined by som
0b50: 65 20 70 72 65 76 69 6f 75 73 20 68 65 61 64 65  e previous heade
0b60: 72 20 66 69 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65  r file..*/.#ifde
0b70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0b80: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
0b90: 56 45 52 53 49 4f 4e 0a 23 65 6e 64 69 66 0a 23  VERSION.#endif.#
0ba0: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52  ifdef SQLITE_VER
0bb0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23 20 75 6e  SION_NUMBER.# un
0bc0: 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49  def SQLITE_VERSI
0bd0: 4f 4e 5f 4e 55 4d 42 45 52 0a 23 65 6e 64 69 66  ON_NUMBER.#endif
0be0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
0bf0: 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 4c  : Compile-Time L
0c00: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
0c10: 75 6d 62 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  umbers.**.** ^(T
0c20: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
0c30: 4f 4e 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ON] C preprocess
0c40: 6f 72 20 6d 61 63 72 6f 20 69 6e 20 74 68 65 20  or macro in the 
0c50: 73 71 6c 69 74 65 33 2e 68 20 68 65 61 64 65 72  sqlite3.h header
0c60: 0a 2a 2a 20 65 76 61 6c 75 61 74 65 73 20 74 6f  .** evaluates to
0c70: 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
0c80: 6c 20 74 68 61 74 20 69 73 20 74 68 65 20 53 51  l that is the SQ
0c90: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 69 6e 20  Lite version in 
0ca0: 74 68 65 0a 2a 2a 20 66 6f 72 6d 61 74 20 22 58  the.** format "X
0cb0: 2e 59 2e 5a 22 20 77 68 65 72 65 20 58 20 69 73  .Y.Z" where X is
0cc0: 20 74 68 65 20 6d 61 6a 6f 72 20 76 65 72 73 69   the major versi
0cd0: 6f 6e 20 6e 75 6d 62 65 72 20 28 61 6c 77 61 79  on number (alway
0ce0: 73 20 33 20 66 6f 72 0a 2a 2a 20 53 51 4c 69 74  s 3 for.** SQLit
0cf0: 65 33 29 20 61 6e 64 20 59 20 69 73 20 74 68 65  e3) and Y is the
0d00: 20 6d 69 6e 6f 72 20 76 65 72 73 69 6f 6e 20 6e   minor version n
0d10: 75 6d 62 65 72 20 61 6e 64 20 5a 20 69 73 20 74  umber and Z is t
0d20: 68 65 20 72 65 6c 65 61 73 65 20 6e 75 6d 62 65  he release numbe
0d30: 72 2e 29 5e 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  r.)^.** ^(The [S
0d40: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
0d50: 4d 42 45 52 5d 20 43 20 70 72 65 70 72 6f 63 65  MBER] C preproce
0d60: 73 73 6f 72 20 6d 61 63 72 6f 20 72 65 73 6f 6c  ssor macro resol
0d70: 76 65 73 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ves to an intege
0d80: 72 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 76 61  r.** with the va
0d90: 6c 75 65 20 28 58 2a 31 30 30 30 30 30 30 20 2b  lue (X*1000000 +
0da0: 20 59 2a 31 30 30 30 20 2b 20 5a 29 20 77 68 65   Y*1000 + Z) whe
0db0: 72 65 20 58 2c 20 59 2c 20 61 6e 64 20 5a 20 61  re X, Y, and Z a
0dc0: 72 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 6e  re the same.** n
0dd0: 75 6d 62 65 72 73 20 75 73 65 64 20 69 6e 20 5b  umbers used in [
0de0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2e  SQLITE_VERSION].
0df0: 29 5e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )^.** The SQLITE
0e00: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
0e10: 66 6f 72 20 61 6e 79 20 67 69 76 65 6e 20 72 65  for any given re
0e20: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
0e30: 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
0e40: 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20  larger than the 
0e50: 72 65 6c 65 61 73 65 20 66 72 6f 6d 20 77 68 69  release from whi
0e60: 63 68 20 69 74 20 69 73 20 64 65 72 69 76 65 64  ch it is derived
0e70: 2e 20 20 45 69 74 68 65 72 20 59 20 77 69 6c 6c  .  Either Y will
0e80: 0a 2a 2a 20 62 65 20 68 65 6c 64 20 63 6f 6e 73  .** be held cons
0e90: 74 61 6e 74 20 61 6e 64 20 5a 20 77 69 6c 6c 20  tant and Z will 
0ea0: 62 65 20 69 6e 63 72 65 6d 65 6e 74 65 64 20 6f  be incremented o
0eb0: 72 20 65 6c 73 65 20 59 20 77 69 6c 6c 20 62 65  r else Y will be
0ec0: 20 69 6e 63 72 65 6d 65 6e 74 65 64 0a 2a 2a 20   incremented.** 
0ed0: 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 72 65  and Z will be re
0ee0: 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a  set to zero..**.
0ef0: 2a 2a 20 53 69 6e 63 65 20 5b 76 65 72 73 69 6f  ** Since [versio
0f00: 6e 20 33 2e 36 2e 31 38 5d 20 28 5b 64 61 74 65  n 3.6.18] ([date
0f10: 6f 66 3a 33 2e 36 2e 31 38 5d 29 2c 20 0a 2a 2a  of:3.6.18]), .**
0f20: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
0f30: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
0f40: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
0f50: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
0f60: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
0f70: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
0f80: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
0f90: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
0fa0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
0fb0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
0fc0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
0fd0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
0fe0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
0ff0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
1000: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
1010: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
1020: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
1030: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
1040: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
1050: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
1060: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
1070: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
1080: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e  -in (UTC) and an
1090: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66   SHA1.** hash of
10a0: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72   the entire sour
10b0: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53  ce tree..**.** S
10c0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
10d0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c  3_libversion()],
10e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  .** [sqlite3_lib
10f0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
1100: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72  ], [sqlite3_sour
1110: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ceid()],.** [sql
1120: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
1130: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
1140: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  e_id()]..*/.#def
1150: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
1160: 4f 4e 20 20 20 20 20 20 20 20 22 2d 2d 56 45 52  ON        "--VER
1170: 53 2d 2d 22 0a 23 64 65 66 69 6e 65 20 53 51 4c  S--".#define SQL
1180: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1190: 45 52 20 2d 2d 56 45 52 53 49 4f 4e 2d 4e 55 4d  ER --VERSION-NUM
11a0: 42 45 52 2d 2d 0a 23 64 65 66 69 6e 65 20 53 51  BER--.#define SQ
11b0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20  LITE_SOURCE_ID  
11c0: 20 20 20 20 22 2d 2d 53 4f 55 52 43 45 2d 49 44      "--SOURCE-ID
11d0: 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  --"../*.** CAPI3
11e0: 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
11f0: 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75  brary Version Nu
1200: 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  mbers.** KEYWORD
1210: 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  S: sqlite3_versi
1220: 6f 6e 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  on sqlite3_sourc
1230: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  eid.**.** These 
1240: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69  interfaces provi
1250: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  de the same info
1260: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b  rmation as the [
1270: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c  SQLITE_VERSION],
1280: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1290: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64  ION_NUMBER], and
12a0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
12b0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
12c0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74  or macros.** but
12d0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20   are associated 
12e0: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
12f0: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
1300: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28  header file.  ^(
1310: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67  Cautious.** prog
1320: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e  rammers might in
1330: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73  clude assert() s
1340: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
1350: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
1360: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74  o.** verify that
1370: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
1380: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66   by these interf
1390: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d  aces match the m
13a0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20  acros in.** the 
13b0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73  header, and thus
13c0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
13d0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a   application is.
13e0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
13f0: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72   matching librar
1400: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c  y and header fil
1410: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  es..**.** <block
1420: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61  quote><pre>.** a
1430: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c  ssert( sqlite3_l
1440: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
1450: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49  ()==SQLITE_VERSI
1460: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20  ON_NUMBER );.** 
1470: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
1480: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1490: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  ),SQLITE_SOURCE_
14a0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73  ID)==0 );.** ass
14b0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
14c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
14d0: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29  ,SQLITE_VERSION)
14e0: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ==0 );.** </pre>
14f0: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1500: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1510: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1520: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e  ing constant con
1530: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f  tains the text o
1540: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  f [SQLITE_VERSIO
1550: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54  N].** macro.  ^T
1560: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
1570: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e  rsion() function
1580: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1590: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20  er to the.** to 
15a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  the sqlite3_vers
15b0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
15c0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  stant.  The sqli
15d0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
15e0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
15f0: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65  provided for use
1600: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44   in DLLs since D
1610: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79  LL users usually
1620: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20   do not have.** 
1630: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
1640: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
1650: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c  s within the DLL
1660: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
1670: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1680: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20  mber() function 
1690: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
16a0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b  er equal to.** [
16b0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
16c0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71  UMBER].  ^The sq
16d0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
16e0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
16f0: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
1700: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73  to a string cons
1710: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65  tant whose value
1720: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
1730: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1740: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1750: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e  processor macro.
1760: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
1770: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   [sqlite_version
1780: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f  ()] and [sqlite_
1790: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f  source_id()]..*/
17a0: 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
17b0: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65  onst char sqlite
17c0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 63 6f 6e  3_version[];.con
17d0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
17e0: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64  _libversion(void
17f0: 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
1800: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
1810: 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74  void);.int sqlit
1820: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
1830: 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  mber(void);../*.
1840: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
1850: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f  -Time Library Co
1860: 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e  mpilation Option
1870: 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a  s Diagnostics.**
1880: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1890: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75  _compileoption_u
18a0: 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  sed() function r
18b0: 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a  eturns 0 or 1 .*
18c0: 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65  * indicating whe
18d0: 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69  ther the specifi
18e0: 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65  ed option was de
18f0: 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d  fined at .** com
1900: 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65  pile time.  ^The
1910: 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20   SQLITE_ prefix 
1920: 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66  may be omitted f
1930: 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69  rom the .** opti
1940: 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74  on name passed t
1950: 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  o sqlite3_compil
1960: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20  eoption_used(). 
1970: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
1980: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
1990: 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f  on_get() functio
19a0: 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69  n allows iterati
19b0: 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c  ng.** over the l
19c0: 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74  ist of options t
19d0: 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64  hat were defined
19e0: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
19f0: 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67   by.** returning
1a00: 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c   the N-th compil
1a10: 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74  e time option st
1a20: 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20  ring.  ^If N is 
1a30: 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a  out of range,.**
1a40: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1a50: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74  option_get() ret
1a60: 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
1a70: 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  ter.  ^The SQLIT
1a80: 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73  E_ .** prefix is
1a90: 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e   omitted from an
1aa0: 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  y strings return
1ab0: 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
1ac0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1ad0: 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75  get()..**.** ^Su
1ae0: 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69  pport for the di
1af0: 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f  agnostic functio
1b00: 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ns sqlite3_compi
1b10: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a  leoption_used().
1b20: 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  ** and sqlite3_c
1b30: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b40: 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  () may be omitte
1b50: 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20  d by specifying 
1b60: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
1b70: 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49  OMIT_COMPILEOPTI
1b80: 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e  ON_DIAGS] option
1b90: 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
1ba0: 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
1bb0: 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  : SQL functions 
1bc0: 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f  [sqlite_compileo
1bd0: 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e  ption_used()] an
1be0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  d.** [sqlite_com
1bf0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1c00: 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69  ] and the [compi
1c10: 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d  le_options pragm
1c20: 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  a]..*/.#ifndef S
1c30: 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49  QLITE_OMIT_COMPI
1c40: 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 69  LEOPTION_DIAGS.i
1c50: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nt sqlite3_compi
1c60: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f  leoption_used(co
1c70: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61  nst char *zOptNa
1c80: 6d 65 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  me);.const char 
1c90: 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65  *sqlite3_compile
1ca0: 6f 70 74 69 6f 6e 5f 67 65 74 28 69 6e 74 20 4e  option_get(int N
1cb0: 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
1cc0: 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
1cd0: 54 6f 20 53 65 65 20 49 66 20 54 68 65 20 4c 69  To See If The Li
1ce0: 62 72 61 72 79 20 49 73 20 54 68 72 65 61 64 73  brary Is Threads
1cf0: 61 66 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  afe.**.** ^The s
1d00: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
1d10: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  e() function ret
1d20: 75 72 6e 73 20 7a 65 72 6f 20 69 66 20 61 6e 64  urns zero if and
1d30: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 53 51 4c 69   only if.** SQLi
1d40: 74 65 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20  te was compiled 
1d50: 77 69 74 68 20 6d 75 74 65 78 69 6e 67 20 63 6f  with mutexing co
1d60: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1d70: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1d80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1d90: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1da0: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1db0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1dc0: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1dd0: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1de0: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1df0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1e00: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1e10: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1e20: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1e30: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1e40: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1e50: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1e60: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1e70: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1e80: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1e90: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1ea0: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1eb0: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1ec0: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1ed0: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1ee0: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1ef0: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1f00: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1f10: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1f20: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1f30: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1f40: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1f50: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1f60: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1f70: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1f80: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1f90: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1fa0: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1fb0: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1fc0: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1fd0: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1fe0: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1ff0: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
2000: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
2010: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
2020: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
2030: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
2040: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
2050: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
2060: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
2070: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
2080: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
2090: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
20a0: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
20b0: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
20c0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
20d0: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
20e0: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
20f0: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
2100: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
2110: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
2120: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
2130: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
2140: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
2150: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
2160: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
2170: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2180: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2190: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
21a0: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
21b0: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
21c0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
21d0: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
21e0: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
21f0: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2200: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2210: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
2220: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
2230: 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
2240: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
2250: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
2260: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2270: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2280: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2290: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
22a0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
22b0: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
22c0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
22d0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
22e0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
22f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2300: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2310: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
2320: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
2330: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
2340: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
2350: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
2360: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
2370: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2380: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2390: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
23a0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
23b0: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
23c0: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
23d0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23e0: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
23f0: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2400: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2410: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2420: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
2430: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
2440: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
2450: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
2460: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
2470: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2480: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2490: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
24a0: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
24b0: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
24c0: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
24d0: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
24e0: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
24f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2500: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2510: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
2520: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2530: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
2540: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
2550: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
2560: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
2570: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2580: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2590: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
25a0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
25b0: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
25c0: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
25d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
25e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
25f0: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2600: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2610: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
2620: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
2630: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
2640: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
2650: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
2660: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
2670: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2680: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2690: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
26a0: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
26b0: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
26c0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
26d0: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
26e0: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
26f0: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2700: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2710: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
2720: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
2730: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
2740: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
2750: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
2760: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
2770: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2780: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2790: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
27a0: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
27b0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
27c0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
27d0: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
27e0: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
27f0: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2800: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2810: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2820: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
2830: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
2840: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
2850: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
2860: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
2870: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2880: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2890: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
28a0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
28b0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
28c0: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
28d0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
28e0: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
28f0: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2900: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2910: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
2920: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
2930: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
2940: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
2950: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 23 20  sqlite_int64;.# 
2960: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e  ifdef SQLITE_UIN
2970: 54 36 34 5f 54 59 50 45 0a 20 20 20 20 74 79 70  T64_TYPE.    typ
2980: 65 64 65 66 20 53 51 4c 49 54 45 5f 55 49 4e 54  edef SQLITE_UINT
2990: 36 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75  64_TYPE sqlite_u
29a0: 69 6e 74 36 34 3b 0a 23 20 65 6c 73 65 20 20 0a  int64;.# else  .
29b0: 20 20 20 20 74 79 70 65 64 65 66 20 75 6e 73 69      typedef unsi
29c0: 67 6e 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36  gned SQLITE_INT6
29d0: 34 5f 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69  4_TYPE sqlite_ui
29e0: 6e 74 36 34 3b 0a 23 20 65 6e 64 69 66 0a 23 65  nt64;.# endif.#e
29f0: 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43  lif defined(_MSC
2a00: 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64  _VER) || defined
2a10: 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20  (__BORLANDC__). 
2a20: 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34   typedef __int64
2a30: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2a40: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2a50: 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  d __int64 sqlite
2a60: 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20  _uint64;.#else. 
2a70: 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f   typedef long lo
2a80: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e  ng int sqlite_in
2a90: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2aa0: 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e  nsigned long lon
2ab0: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e  g int sqlite_uin
2ac0: 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65  t64;.#endif.type
2ad0: 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  def sqlite_int64
2ae0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a   sqlite3_int64;.
2af0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75  typedef sqlite_u
2b00: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69  int64 sqlite3_ui
2b10: 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20  nt64;../*.** If 
2b20: 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20  compiling for a 
2b30: 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c  processor that l
2b40: 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f  acks floating po
2b50: 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20  int support,.** 
2b60: 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67  substitute integ
2b70: 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d  er for floating-
2b80: 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66  point..*/.#ifdef
2b90: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f   SQLITE_OMIT_FLO
2ba0: 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65  ATING_POINT.# de
2bb0: 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69  fine double sqli
2bc0: 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66  te3_int64.#endif
2bd0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2be0: 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61  : Closing A Data
2bf0: 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
2c00: 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
2c10: 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
2c20: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  e sqlite3_close(
2c30: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c  ) and sqlite3_cl
2c40: 6f 73 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65  ose_v2() routine
2c50: 73 20 61 72 65 20 64 65 73 74 72 75 63 74 6f 72  s are destructor
2c60: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71  s.** for the [sq
2c70: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a  lite3] object..*
2c80: 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
2c90: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
2ca0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2cb0: 28 29 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  () return [SQLIT
2cc0: 45 5f 4f 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20  E_OK] if.** the 
2cd0: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
2ce0: 20 69 73 20 73 75 63 63 65 73 73 66 75 6c 6c 79   is successfully
2cf0: 20 64 65 73 74 72 6f 79 65 64 20 61 6e 64 20 61   destroyed and a
2d00: 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ll associated.**
2d10: 20 72 65 73 6f 75 72 63 65 73 20 61 72 65 20 64   resources are d
2d20: 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a  eallocated..**.*
2d30: 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
2d40: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2d50: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2d60: 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72 65   unfinalized pre
2d70: 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2d80: 6e 74 73 20 6f 72 20 75 6e 66 69 6e 69 73 68 65  nts or unfinishe
2d90: 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70  d sqlite3_backup
2da0: 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20 73 71   objects then sq
2db0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a  lite3_close().**
2dc0: 20 77 69 6c 6c 20 6c 65 61 76 65 20 74 68 65 20   will leave the 
2dd0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2de0: 69 6f 6e 20 6f 70 65 6e 20 61 6e 64 20 72 65 74  ion open and ret
2df0: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  urn [SQLITE_BUSY
2e00: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
2e10: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 73 20  3_close_v2() is 
2e20: 63 61 6c 6c 65 64 20 77 69 74 68 20 75 6e 66 69  called with unfi
2e30: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2e40: 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61   statements.** a
2e50: 6e 64 2f 6f 72 20 75 6e 66 69 6e 69 73 68 65 64  nd/or unfinished
2e60: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 73   sqlite3_backups
2e70: 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
2e80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  ase connection b
2e90: 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75  ecomes.** an unu
2ea0: 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77  sable "zombie" w
2eb0: 68 69 63 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61  hich will automa
2ec0: 74 69 63 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c  tically be deall
2ed0: 6f 63 61 74 65 64 20 77 68 65 6e 20 74 68 65 0a  ocated when the.
2ee0: 2a 2a 20 6c 61 73 74 20 70 72 65 70 61 72 65 64  ** last prepared
2ef0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 66 69   statement is fi
2f00: 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68 65 20 6c  nalized or the l
2f10: 61 73 74 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  ast sqlite3_back
2f20: 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65  up is.** finishe
2f30: 64 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  d.  The sqlite3_
2f40: 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e 74 65 72  close_v2() inter
2f50: 66 61 63 65 20 69 73 20 69 6e 74 65 6e 64 65 64  face is intended
2f60: 20 66 6f 72 20 75 73 65 20 77 69 74 68 0a 2a 2a   for use with.**
2f70: 20 68 6f 73 74 20 6c 61 6e 67 75 61 67 65 73 20   host languages 
2f80: 74 68 61 74 20 61 72 65 20 67 61 72 62 61 67 65  that are garbage
2f90: 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20   collected, and 
2fa0: 77 68 65 72 65 20 74 68 65 20 6f 72 64 65 72 20  where the order 
2fb0: 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64 65 73 74  in which.** dest
2fc0: 72 75 63 74 6f 72 73 20 61 72 65 20 63 61 6c 6c  ructors are call
2fd0: 65 64 20 69 73 20 61 72 62 69 74 72 61 72 79 2e  ed is arbitrary.
2fe0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2ff0: 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69  ons should [sqli
3000: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
3010: 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72  inalize] all [pr
3020: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3030: 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  s],.** [sqlite3_
3040: 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f  blob_close | clo
3050: 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61  se] all [BLOB ha
3060: 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20  ndles], and .** 
3070: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f  [sqlite3_backup_
3080: 66 69 6e 69 73 68 20 7c 20 66 69 6e 69 73 68 5d  finish | finish]
3090: 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61   all [sqlite3_ba
30a0: 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61 73  ckup] objects as
30b0: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
30c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
30d0: 62 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61  bject prior to a
30e0: 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f  ttempting to clo
30f0: 73 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20  se the object.  
3100: 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  ^If.** sqlite3_c
3110: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
3120: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
3130: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
3140: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
3150: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
3160: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
3170: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
3180: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
3190: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
31a0: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
31b0: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
31c0: 4b 5d 20 61 6e 64 20 74 68 65 20 64 65 61 6c 6c  K] and the deall
31d0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65  ocation.** of re
31e0: 73 6f 75 72 63 65 73 20 69 73 20 64 65 66 65 72  sources is defer
31f0: 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70  red until all [p
3200: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
3210: 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c  ts], [BLOB handl
3220: 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  es],.** and [sql
3230: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
3240: 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65  ects are also de
3250: 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  stroyed..**.** ^
3260: 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  If an [sqlite3] 
3270: 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f  object is destro
3280: 79 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  yed while a tran
3290: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
32a0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
32b0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
32c0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
32d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
32e0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
32f0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e  te3_close(C)] an
3300: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
3310: 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20  _v2(C)].** must 
3320: 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c  be either a NULL
3330: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61  .** pointer or a
3340: 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  n [sqlite3] obje
3350: 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69  ct pointer obtai
3360: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3370: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
3380: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
3390: 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
33a0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
33b0: 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20   not previously 
33c0: 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c  closed..** ^Call
33d0: 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ing sqlite3_clos
33e0: 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
33f0: 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68 20 61  lose_v2() with a
3400: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
3410: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68   argument is a h
3420: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
3430: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  /.int sqlite3_cl
3440: 6f 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69  ose(sqlite3*);.i
3450: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3460: 5f 76 32 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  _v2(sqlite3*);..
3470: 2f 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66  /*.** The type f
3480: 6f 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  or a callback fu
3490: 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20  nction..** This 
34a0: 69 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65  is legacy and de
34b0: 70 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73  precated.  It is
34c0: 20 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69   included for hi
34d0: 73 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70  storical.** comp
34e0: 61 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73  atibility and is
34f0: 20 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e   not documented.
3500: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20  .*/.typedef int 
3510: 28 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61  (*sqlite3_callba
3520: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
3530: 61 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a  ar**, char**);..
3540: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3550: 4f 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45  One-Step Query E
3560: 78 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61  xecution Interfa
3570: 63 65 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71  ce.** METHOD: sq
3580: 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 54 68 65 20  lite3.**.** The 
3590: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
35a0: 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63 6f  nterface is a co
35b0: 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70 65  nvenience wrappe
35c0: 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c  r around.** [sql
35d0: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
35e0: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
35f0: 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  p()], and [sqlit
3600: 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a  e3_finalize()],.
3610: 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 61  ** that allows a
3620: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  n application to
3630: 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73 74   run multiple st
3640: 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c 0a  atements of SQL.
3650: 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69 6e  ** without havin
3660: 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20 6f  g to use a lot o
3670: 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a  f C code. .**.**
3680: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
3690: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ec() interface r
36a0: 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  uns zero or more
36b0: 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c 0a   UTF-8 encoded,.
36c0: 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70  ** semicolon-sep
36d0: 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65 6d  arate SQL statem
36e0: 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f  ents passed into
36f0: 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
3700: 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f 6e  t,.** in the con
3710: 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61 74  text of the [dat
3720: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3730: 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 69  ] passed in as i
3740: 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d 65  ts 1st.** argume
3750: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  nt.  ^If the cal
3760: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6f  lback function o
3770: 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d 65  f the 3rd argume
3780: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
3790: 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e  _exec() is not N
37a0: 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ULL, then it is 
37b0: 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63 68  invoked for each
37c0: 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20 63   result row.** c
37d0: 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  oming out of the
37e0: 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20 73   evaluated SQL s
37f0: 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68 65  tatements.  ^The
3800: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
3810: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3820: 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68  () is relayed th
3830: 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74  rough to the 1st
3840: 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63   argument of eac
3850: 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e  h.** callback in
3860: 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74  vocation.  ^If t
3870: 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e  he callback poin
3880: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3890: 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c  xec().** is NULL
38a0: 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61  , then no callba
38b0: 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b  ck is ever invok
38c0: 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f  ed and result ro
38d0: 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65  ws are.** ignore
38e0: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
38f0: 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69  error occurs whi
3900: 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68  le evaluating th
3910: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3920: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20  sqlite3_exec(), 
3940: 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f  then execution o
3950: 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  f the current st
3960: 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e  atement stops an
3970: 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20  d.** subsequent 
3980: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73  statements are s
3990: 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65  kipped.  ^If the
39a0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
39b0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
39c0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  .** is not NULL 
39d0: 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d  then any error m
39e0: 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65  essage is writte
39f0: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
3a00: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
3a10: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
3a20: 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63  ] and passed bac
3a30: 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  k through the 5t
3a40: 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  h parameter..** 
3a50: 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20  To avoid memory 
3a60: 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69  leaks, the appli
3a70: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e  cation should in
3a80: 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72  voke [sqlite3_fr
3a90: 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f  ee()].** on erro
3aa0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
3ab0: 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75  s returned throu
3ac0: 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  gh the 5th param
3ad0: 65 74 65 72 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  eter of.** sqlit
3ae0: 65 33 5f 65 78 65 63 28 29 20 61 66 74 65 72 20  e3_exec() after 
3af0: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
3b00: 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c  e string is no l
3b10: 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a  onger needed..**
3b20: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
3b30: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3b40: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3b50: 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f  NULL and no erro
3b60: 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65  rs.** occur, the
3b70: 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  n sqlite3_exec()
3b80: 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e 74 65   sets the pointe
3b90: 72 20 69 6e 20 69 74 73 20 35 74 68 20 70 61 72  r in its 5th par
3ba0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c  ameter to.** NUL
3bb0: 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  L before returni
3bc0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ng..**.** ^If an
3bd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3be0: 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
3bf0: 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73   non-zero, the s
3c00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
3c10: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
3c20: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 77 69   SQLITE_ABORT wi
3c30: 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74  thout invoking t
3c40: 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67 61 69  he callback agai
3c50: 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74  n and.** without
3c60: 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62   running any sub
3c70: 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74 61 74  sequent SQL stat
3c80: 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
3c90: 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 20  he 2nd argument 
3ca0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3cb0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 66  xec() callback f
3cc0: 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a  unction is the.*
3cd0: 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  * number of colu
3ce0: 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
3cf0: 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61 72 67  t.  ^The 3rd arg
3d00: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3d10: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63  ite3_exec().** c
3d20: 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72  allback is an ar
3d30: 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
3d40: 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74 61 69  to strings obtai
3d50: 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a  ned as if from.*
3d60: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
3d70: 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66  n_text()], one f
3d80: 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20  or each column. 
3d90: 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20   ^If an element 
3da0: 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72  of a.** result r
3db0: 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20  ow is NULL then 
3dc0: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
3dd0: 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  g string pointer
3de0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69   for the.** sqli
3df0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3e00: 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ack is a NULL po
3e10: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34 74 68  inter.  ^The 4th
3e20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3e30: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3e40: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3e50: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
3e60: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 77  ers to strings w
3e70: 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74  here each.** ent
3e80: 72 79 20 72 65 70 72 65 73 65 6e 74 73 20 74 68  ry represents th
3e90: 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72 65 73  e name of corres
3ea0: 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74 20 63  ponding result c
3eb0: 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65  olumn as obtaine
3ec0: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
3ed0: 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
3ee0: 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
3ef0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
3f00: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f10: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3f20: 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  er, a pointer.**
3f30: 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
3f40: 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65  ing, or a pointe
3f50: 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 20  r that contains 
3f60: 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63 65 20  only whitespace 
3f70: 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63  and/or .** SQL c
3f80: 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f  omments, then no
3f90: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
3fa0: 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 61 6e  are evaluated an
3fb0: 64 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  d the database.*
3fc0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
3fd0: 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74  ..**.** Restrict
3fe0: 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ions:.**.** <ul>
3ff0: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
4000: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 65 6e  lication must en
4010: 73 75 72 65 20 74 68 61 74 20 74 68 65 20 31 73  sure that the 1s
4020: 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
4030: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
4040: 20 20 20 20 20 20 69 73 20 61 20 76 61 6c 69 64        is a valid
4050: 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74 61 62   and open [datab
4060: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
4070: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
4080: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
4090: 74 20 63 6c 6f 73 65 20 74 68 65 20 5b 64 61 74  t close the [dat
40a0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
40b0: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
40c0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
40d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
40e0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
40f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
4100: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
4110: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
4120: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
4130: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
4140: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
4150: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
4160: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
4170: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
4180: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
4190: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
41a0: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
41b0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
41c0: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
41d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
41f0: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
4200: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
4210: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
4220: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4230: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
4240: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
4250: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
4260: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
4270: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
4280: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
4290: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
42a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
42b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
42c0: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
42d0: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
42e0: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
42f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4300: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
4310: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
4320: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
4330: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
4340: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
4350: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
4360: 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a  de definitions}.
4370: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
4380: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
4390: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
43a0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
43b0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
43c0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
43d0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
43e0: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
43f0: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
4400: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
4410: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
4420: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
4430: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
4440: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4450: 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  code definitions
4460: 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ].*/.#define SQL
4470: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
4480: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
4490: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
44a0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
44b0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
44c0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
44d0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
44e0: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
44f0: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4510: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4520: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4530: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4540: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4550: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4560: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
4570: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
4580: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4590: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
45a0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
45b0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
45c0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
45d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
45e0: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
45f0: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4600: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4610: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4620: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4630: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4640: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4650: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4660: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4670: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
4680: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
4690: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
46a0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
46b0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
46c0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
46d0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
46e0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
46f0: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4700: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4710: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4720: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4730: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4740: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4750: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4760: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4770: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
4780: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
4790: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
47a0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
47b0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
47c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
47d0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
47e0: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
47f0: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4800: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4810: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4820: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4830: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4840: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4850: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4860: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4870: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
4880: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
4890: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
48a0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
48b0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
48c0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
48d0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
48e0: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
48f0: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4900: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4910: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4920: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4930: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4940: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4950: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4960: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4970: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
4980: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
4990: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
49a0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
49b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
49c0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
49d0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
49e0: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
49f0: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4a00: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4a10: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4a20: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4a30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4a40: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4a50: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4a60: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
4a80: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
4a90: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
4aa0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
4ab0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
4ac0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4ad0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4ae0: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4af0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4b00: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4b10: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4b20: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4b30: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4b40: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4b50: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4b60: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4b70: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4b80: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4b90: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4ba0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4bb0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4bc0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4bd0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4be0: 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20  e SQLITE_NOTICE 
4bf0: 20 20 20 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74       27   /* Not
4c00: 69 66 69 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20  ifications from 
4c10: 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f  sqlite3_log() */
4c20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c30: 57 41 52 4e 49 4e 47 20 20 20 20 20 32 38 20 20  WARNING     28  
4c40: 20 2f 2a 20 57 61 72 6e 69 6e 67 73 20 66 72 6f   /* Warnings fro
4c50: 6d 20 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20  m sqlite3_log() 
4c60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4c70: 45 5f 52 4f 57 20 20 20 20 20 20 20 20 20 31 30  E_ROW         10
4c80: 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74  0  /* sqlite3_st
4c90: 65 70 28 29 20 68 61 73 20 61 6e 6f 74 68 65 72  ep() has another
4ca0: 20 72 6f 77 20 72 65 61 64 79 20 2a 2f 0a 23 64   row ready */.#d
4cb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e  efine SQLITE_DON
4cc0: 45 20 20 20 20 20 20 20 20 31 30 31 20 20 2f 2a  E        101  /*
4cd0: 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
4ce0: 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
4cf0: 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64  cuting */./* end
4d00: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4d10: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
4d20: 45 46 3a 20 45 78 74 65 6e 64 65 64 20 52 65 73  EF: Extended Res
4d30: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4d40: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4d50: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66   result code def
4d60: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4d70: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
4d80: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
4d90: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
4da0: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4db0: 33 30 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72  30 integer.** [r
4dc0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48  esult codes].  H
4dd0: 6f 77 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e  owever, experien
4de0: 63 65 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61  ce has shown tha
4df0: 74 20 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65  t many of.** the
4e00: 73 65 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  se result codes 
4e10: 61 72 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67  are too coarse-g
4e20: 72 61 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f  rained.  They do
4e30: 20 6e 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a   not provide as.
4e40: 2a 2a 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74  ** much informat
4e50: 69 6f 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65  ion about proble
4e60: 6d 73 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72  ms as programmer
4e70: 73 20 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49  s might like.  I
4e80: 6e 20 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a  n an effort to.*
4e90: 2a 20 61 64 64 72 65 73 73 20 74 68 69 73 2c 20  * address this, 
4ea0: 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  newer versions o
4eb0: 66 20 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f  f SQLite (versio
4ec0: 6e 20 33 2e 33 2e 38 20 5b 64 61 74 65 6f 66 3a  n 3.3.8 [dateof:
4ed0: 33 2e 33 2e 38 5d 0a 2a 2a 20 61 6e 64 20 6c 61  3.3.8].** and la
4ee0: 74 65 72 29 20 69 6e 63 6c 75 64 65 0a 2a 2a 20  ter) include.** 
4ef0: 73 75 70 70 6f 72 74 20 66 6f 72 20 61 64 64 69  support for addi
4f00: 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74 20 63 6f  tional result co
4f10: 64 65 73 20 74 68 61 74 20 70 72 6f 76 69 64 65  des that provide
4f20: 20 6d 6f 72 65 20 64 65 74 61 69 6c 65 64 20 69   more detailed i
4f30: 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62  nformation.** ab
4f40: 6f 75 74 20 65 72 72 6f 72 73 2e 20 54 68 65 73  out errors. Thes
4f50: 65 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  e [extended resu
4f60: 6c 74 20 63 6f 64 65 73 5d 20 61 72 65 20 65 6e  lt codes] are en
4f70: 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
4f80: 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61  d.** on a per da
4f90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
4fa0: 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68  n basis using th
4fb0: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  e.** [sqlite3_ex
4fc0: 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
4fd0: 64 65 73 28 29 5d 20 41 50 49 2e 20 20 4f 72 2c  des()] API.  Or,
4fe0: 20 74 68 65 20 65 78 74 65 6e 64 65 64 20 63 6f   the extended co
4ff0: 64 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 6d 6f  de for.** the mo
5000: 73 74 20 72 65 63 65 6e 74 20 65 72 72 6f 72 20  st recent error 
5010: 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
5020: 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
5030: 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
5040: 64 65 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  de()]..*/.#defin
5050: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
5060: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
5070: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5080: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
5090: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
50a0: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20  ORT_READ        
50b0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
50c0: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
50d0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
50e0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  TE             (
50f0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
5100: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5110: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
5120: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  C             (S
5130: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
5140: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5150: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
5160: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51  SYNC         (SQ
5170: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c  LITE_IOERR | (5<
5180: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5190: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41  ITE_IOERR_TRUNCA
51a0: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TE          (SQL
51b0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
51c0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51d0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
51e0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
51f0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
5200: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5210: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
5220: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
5230: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
5240: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5250: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
5260: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5270: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29  _IOERR | (9<<8))
5280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5290: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20  IOERR_DELETE    
52a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52b0: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
52c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52d0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
52e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
52f0: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
5300: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5310: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
5320: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5330: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
5340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5350: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20  IOERR_ACCESS    
5360: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5370: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29  IOERR | (13<<8))
5380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5390: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52  IOERR_CHECKRESER
53a0: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f  VEDLOCK (SQLITE_
53b0: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29  IOERR | (14<<8))
53c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53d0: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20  IOERR_LOCK      
53e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
53f0: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29  IOERR | (15<<8))
5400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5410: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20  IOERR_CLOSE     
5420: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5430: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29  IOERR | (16<<8))
5440: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5450: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20  IOERR_DIR_CLOSE 
5460: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5470: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29  IOERR | (17<<8))
5480: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5490: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20  IOERR_SHMOPEN   
54a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
54b0: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29  IOERR | (18<<8))
54c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54d0: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20  IOERR_SHMSIZE   
54e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
54f0: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29  IOERR | (19<<8))
5500: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5510: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20  IOERR_SHMLOCK   
5520: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5530: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29  IOERR | (20<<8))
5540: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5550: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20  IOERR_SHMMAP    
5560: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5570: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29  IOERR | (21<<8))
5580: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5590: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20  IOERR_SEEK      
55a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
55b0: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29  IOERR | (22<<8))
55c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55d0: 49 4f 45 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45  IOERR_DELETE_NOE
55e0: 4e 54 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  NT      (SQLITE_
55f0: 49 4f 45 52 52 20 7c 20 28 32 33 3c 3c 38 29 29  IOERR | (23<<8))
5600: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5610: 49 4f 45 52 52 5f 4d 4d 41 50 20 20 20 20 20 20  IOERR_MMAP      
5620: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5630: 49 4f 45 52 52 20 7c 20 28 32 34 3c 3c 38 29 29  IOERR | (24<<8))
5640: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5650: 49 4f 45 52 52 5f 47 45 54 54 45 4d 50 50 41 54  IOERR_GETTEMPPAT
5660: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
5670: 49 4f 45 52 52 20 7c 20 28 32 35 3c 3c 38 29 29  IOERR | (25<<8))
5680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5690: 49 4f 45 52 52 5f 43 4f 4e 56 50 41 54 48 20 20  IOERR_CONVPATH  
56a0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56b0: 49 4f 45 52 52 20 7c 20 28 32 36 3c 3c 38 29 29  IOERR | (26<<8))
56c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56d0: 49 4f 45 52 52 5f 56 4e 4f 44 45 20 20 20 20 20  IOERR_VNODE     
56e0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
56f0: 49 4f 45 52 52 20 7c 20 28 32 37 3c 3c 38 29 29  IOERR | (27<<8))
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 49 4f 45 52 52 5f 41 55 54 48 20 20 20 20 20 20  IOERR_AUTH      
5720: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5730: 49 4f 45 52 52 20 7c 20 28 32 38 3c 3c 38 29 29  IOERR | (28<<8))
5740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5750: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43  LOCKED_SHAREDCAC
5760: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  HE      (SQLITE_
5770: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29  LOCKED |  (1<<8)
5780: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5790: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20  _BUSY_RECOVERY  
57a0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
57b0: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38  _BUSY   |  (1<<8
57c0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
57d0: 45 5f 42 55 53 59 5f 53 4e 41 50 53 48 4f 54 20  E_BUSY_SNAPSHOT 
57e0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
57f0: 45 5f 42 55 53 59 20 20 20 7c 20 20 28 32 3c 3c  E_BUSY   |  (2<<
5800: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5810: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45  TE_CANTOPEN_NOTE
5820: 4d 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49  MPDIR      (SQLI
5830: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31  TE_CANTOPEN | (1
5840: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5850: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53  LITE_CANTOPEN_IS
5860: 44 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51  DIR          (SQ
5870: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20  LITE_CANTOPEN | 
5880: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5890: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f  SQLITE_CANTOPEN_
58a0: 46 55 4c 4c 50 41 54 48 20 20 20 20 20 20 20 28  FULLPATH       (
58b0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
58c0: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
58d0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
58e0: 4e 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20  N_CONVPATH      
58f0: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
5900: 4e 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  N | (4<<8)).#def
5910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
5920: 50 54 5f 56 54 41 42 20 20 20 20 20 20 20 20 20  PT_VTAB         
5930: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52 52 55     (SQLITE_CORRU
5940: 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  PT | (1<<8)).#de
5950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5960: 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20 20 20  ONLY_RECOVERY   
5970: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5980: 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29 0a 23  ONLY | (1<<8)).#
5990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
59a0: 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43 4b 20  ADONLY_CANTLOCK 
59b0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
59c0: 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38 29 29  ADONLY | (2<<8))
59d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
59e0: 52 45 41 44 4f 4e 4c 59 5f 52 4f 4c 4c 42 41 43  READONLY_ROLLBAC
59f0: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
5a00: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 33 3c 3c 38  READONLY | (3<<8
5a10: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a20: 45 5f 52 45 41 44 4f 4e 4c 59 5f 44 42 4d 4f 56  E_READONLY_DBMOV
5a30: 45 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ED        (SQLIT
5a40: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 34 3c  E_READONLY | (4<
5a50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5a60: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41  ITE_ABORT_ROLLBA
5a70: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  CK          (SQL
5a80: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c  ITE_ABORT | (2<<
5a90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5aa0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 48  TE_CONSTRAINT_CH
5ab0: 45 43 4b 20 20 20 20 20 20 20 20 28 53 51 4c 49  ECK        (SQLI
5ac0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5ad0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5ae0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5af0: 54 5f 43 4f 4d 4d 49 54 48 4f 4f 4b 20 20 20 28  T_COMMITHOOK   (
5b00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5b10: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5b20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5b30: 52 41 49 4e 54 5f 46 4f 52 45 49 47 4e 4b 45 59  RAINT_FOREIGNKEY
5b40: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5b50: 52 41 49 4e 54 20 7c 20 28 33 3c 3c 38 29 29 0a  RAINT | (3<<8)).
5b60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5b70: 4f 4e 53 54 52 41 49 4e 54 5f 46 55 4e 43 54 49  ONSTRAINT_FUNCTI
5b80: 4f 4e 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  ON     (SQLITE_C
5b90: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 34 3c 3c  ONSTRAINT | (4<<
5ba0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5bb0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4e 4f  TE_CONSTRAINT_NO
5bc0: 54 4e 55 4c 4c 20 20 20 20 20 20 28 53 51 4c 49  TNULL      (SQLI
5bd0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5be0: 28 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (5<<8)).#define 
5bf0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c00: 54 5f 50 52 49 4d 41 52 59 4b 45 59 20 20 20 28  T_PRIMARYKEY   (
5c10: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5c20: 54 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  T | (6<<8)).#def
5c30: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5c40: 52 41 49 4e 54 5f 54 52 49 47 47 45 52 20 20 20  RAINT_TRIGGER   
5c50: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5c60: 52 41 49 4e 54 20 7c 20 28 37 3c 3c 38 29 29 0a  RAINT | (7<<8)).
5c70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5c80: 4f 4e 53 54 52 41 49 4e 54 5f 55 4e 49 51 55 45  ONSTRAINT_UNIQUE
5c90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5ca0: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 38 3c 3c  ONSTRAINT | (8<<
5cb0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5cc0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 56 54  TE_CONSTRAINT_VT
5cd0: 41 42 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  AB         (SQLI
5ce0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
5cf0: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
5d00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5d10: 54 5f 52 4f 57 49 44 20 20 20 20 20 20 20 20 28  T_ROWID        (
5d20: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5d30: 54 20 7c 28 31 30 3c 3c 38 29 29 0a 23 64 65 66  T |(10<<8)).#def
5d40: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5d50: 45 5f 52 45 43 4f 56 45 52 5f 57 41 4c 20 20 20  E_RECOVER_WAL   
5d60: 20 20 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43     (SQLITE_NOTIC
5d70: 45 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  E | (1<<8)).#def
5d80: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 49 43  ine SQLITE_NOTIC
5d90: 45 5f 52 45 43 4f 56 45 52 5f 52 4f 4c 4c 42 41  E_RECOVER_ROLLBA
5da0: 43 4b 20 28 53 51 4c 49 54 45 5f 4e 4f 54 49 43  CK (SQLITE_NOTIC
5db0: 45 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  E | (2<<8)).#def
5dc0: 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49  ine SQLITE_WARNI
5dd0: 4e 47 5f 41 55 54 4f 49 4e 44 45 58 20 20 20 20  NG_AUTOINDEX    
5de0: 20 20 20 28 53 51 4c 49 54 45 5f 57 41 52 4e 49     (SQLITE_WARNI
5df0: 4e 47 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65  NG | (1<<8)).#de
5e00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
5e10: 5f 55 53 45 52 20 20 20 20 20 20 20 20 20 20 20  _USER           
5e20: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 55 54 48      (SQLITE_AUTH
5e30: 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69   | (1<<8)).#defi
5e40: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 5f 4c 4f 41  ne SQLITE_OK_LOA
5e50: 44 5f 50 45 52 4d 41 4e 45 4e 54 4c 59 20 20 20  D_PERMANENTLY   
5e60: 20 20 28 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 28    (SQLITE_OK | (
5e70: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
5e80: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
5e90: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
5ea0: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
5eb0: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
5ec0: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
5ed0: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5ee0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5ef0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5f00: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5f10: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5f20: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5f30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5f40: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5f50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f60: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5f70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5f80: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
5f90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5fa0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5fb0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
5fc0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5fd0: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5fe0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ff0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6000: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
6010: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
6020: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
6030: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6040: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6050: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
6060: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
6070: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
6080: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6090: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
60a0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
60b0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
60c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60d0: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
60e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
60f0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6100: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6110: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
6120: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
6130: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6140: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
6170: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6180: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6190: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
61a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61b0: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
61c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
61d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
61e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61f0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
6200: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6210: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6220: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6230: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
6240: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
6250: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6270: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
6280: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
6290: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
62a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62b0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
62c0: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
62d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
62e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62f0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
6300: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
6310: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6320: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6330: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
6340: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
6350: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6360: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6370: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
6380: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
6390: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
63a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
63b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
63c0: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
63d0: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
63e0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
63f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6400: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6410: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
6420: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
6430: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6440: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6450: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6460: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6470: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
6480: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6490: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
64a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
64b0: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
64c0: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
64d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
64e0: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
64f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6500: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
6510: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
6520: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
6530: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
6540: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
6550: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
6560: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
6570: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6580: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
6590: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
65a0: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
65b0: 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74   of these.** bit
65c0: 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69   values expressi
65d0: 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72  ng I/O character
65e0: 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61  istics of the ma
65f0: 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65  ss storage.** de
6600: 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20  vice that holds 
6610: 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68  the file that th
6620: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
6630: 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73  thods].** refers
6640: 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53   to..**.** The S
6650: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
6660: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
6670: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
6680: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
6690: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
66a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
66b0: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
66c0: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
66d0: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
66e0: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
66f0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
6700: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
6710: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
6720: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
6730: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
6740: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
6750: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
6760: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
6770: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
6780: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
6790: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
67a0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
67b0: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
67c0: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
67d0: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
67e0: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
67f0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
6800: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
6810: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
6820: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6830: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
6840: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
6850: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
6860: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
6870: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
6880: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6890: 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  CAP_POWERSAFE_OV
68a0: 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79  ERWRITE property
68b0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61   means that.** a
68c0: 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c  fter reboot foll
68d0: 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72  owing a crash or
68e0: 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65   power loss, the
68f0: 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61   only bytes in a
6900: 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65  .** file that we
6910: 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68  re written at th
6920: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65  e application le
6930: 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63  vel might have c
6940: 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68  hanged.** and th
6950: 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65  at adjacent byte
6960: 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69  s, even bytes wi
6970: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65  thin the same se
6980: 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72  ctor are.** guar
6990: 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63  anteed to be unc
69a0: 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c  hanged.  The SQL
69b0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
69c0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a  TABLE_WHEN_OPEN.
69d0: 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65  ** flag indicate
69e0: 73 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  s that a file ca
69f0: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
6a00: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
6a10: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
6a20: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
6a30: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6a40: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
6a50: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
6a60: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
6a70: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
6a80: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
6a90: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
6aa0: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ges..*/.#define 
6ab0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6ac0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
6ad0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
6ae0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6af0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
6b00: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6b10: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6b20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6b30: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
6b40: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
6b50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6b60: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
6b70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6b80: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
6b90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
6ba0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
6bb0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
6bc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6bd0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
6be0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
6bf0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6c00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6c10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6c20: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
6c30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6c40: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
6c50: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
6c60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6c70: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
6c80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c90: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
6ca0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6cb0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
6cc0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
6cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6ce0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
6cf0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6d00: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
6d10: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6d20: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
6d30: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
6d40: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6d50: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6d60: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
6d70: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6d80: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
6d90: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  E              0
6da0: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00002000../*.**
6db0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
6dc0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
6dd0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
6de0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
6df0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6e00: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
6e10: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6e20: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6e30: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6e40: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
6e50: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6e60: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6e70: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6e80: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6e90: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6ea0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6eb0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
6ec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6ed0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
6ee0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6ef0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
6f00: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6f10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6f20: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6f30: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
6f40: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
6f50: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6f60: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6f70: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6f80: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6f90: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6fa0: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
6fb0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
6fc0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
6fd0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6fe0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
6ff0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
7000: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
7010: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
7020: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
7030: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
7040: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
7050: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
7060: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
7070: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
7080: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
7090: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
70a0: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
70b0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
70c0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
70d0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
70e0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
70f0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
7100: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
7110: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
7120: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
7130: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
7140: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
7150: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
7160: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
7170: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
7180: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
7190: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
71a0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
71b0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
71c0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
71d0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
71e0: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
71f0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
7200: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
7210: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
7220: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
7230: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
7240: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
7250: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
7260: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
7270: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
7280: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
7290: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
72a0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
72b0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
72c0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
72d0: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
72e0: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
72f0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
7300: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
7310: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
7320: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
7330: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
7340: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
7350: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
7360: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
7370: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
7380: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
7390: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
73a0: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
73b0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
73c0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
73d0: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
73e0: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
73f0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
7400: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
7410: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
7420: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
7430: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
7440: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7450: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
7460: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
7470: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7480: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
7490: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
74a0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
74b0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
74c0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
74d0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
74e0: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
74f0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
7500: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
7510: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
7520: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
7530: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
7540: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
7550: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
7560: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
7570: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7580: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
7590: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
75a0: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
75b0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
75c0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
75d0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
75e0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
75f0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
7600: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
7610: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7620: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
7630: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
7640: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
7650: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
7660: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
7670: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7680: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
7690: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
76a0: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
76b0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
76c0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
76d0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
76e0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
76f0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
7700: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7710: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
7720: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
7730: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
7740: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
7750: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7760: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
7770: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
7780: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7790: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
77a0: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
77b0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
77c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
77d0: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
77e0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
77f0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
7800: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
7810: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
7820: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
7830: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
7840: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
7850: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
7860: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
7870: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
7880: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
7890: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
78a0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
78b0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
78c0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
78d0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
78e0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
78f0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
7900: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7910: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
7920: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
7930: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
7940: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7950: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
7960: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
7970: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
7980: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
7990: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
79a0: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
79b0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
79c0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
79d0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
79e0: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
79f0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7a00: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
7a10: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
7a20: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7a30: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
7a40: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
7a50: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
7a60: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
7a70: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
7a80: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
7a90: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
7aa0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
7ab0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
7ac0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
7ad0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
7ae0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
7af0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
7b00: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
7b10: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
7b20: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
7b30: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
7b40: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
7b50: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
7b60: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
7b70: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
7b80: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
7b90: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
7ba0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
7bb0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
7bc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
7bd0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
7be0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7bf0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
7c00: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7c10: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
7c20: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
7c30: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
7c40: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
7c50: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
7c60: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
7c70: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7c80: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
7c90: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
7ca0: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
7cb0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
7cc0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
7cd0: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
7ce0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
7cf0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
7d00: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
7d10: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
7d20: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
7d30: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
7d40: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
7d50: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7d60: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7d70: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7d80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7d90: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7da0: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
7db0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
7dc0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
7dd0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7de0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
7df0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
7e00: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
7e10: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7e20: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
7e30: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
7e40: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
7e50: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7e60: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7e70: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7e80: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7e90: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7ea0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
7eb0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
7ec0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
7ed0: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
7ee0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
7ef0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
7f00: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
7f10: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7f20: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
7f30: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
7f40: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
7f50: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7f60: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
7f70: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
7f80: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
7f90: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
7fa0: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
7fb0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
7fc0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
7fd0: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
7fe0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
7ff0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
8000: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
8010: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
8020: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
8030: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f  * A [file contro
8040: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74  l opcodes | list
8050: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
8060: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
8070: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
8080: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
8090: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
80a0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
80b0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
80c0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
80d0: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
80e0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
80f0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
8100: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
8110: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
8120: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
8130: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
8140: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
8150: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
8160: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
8170: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
8180: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
8190: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
81a0: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
81b0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
81c0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
81d0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
81e0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
81f0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
8200: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
8210: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
8220: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
8230: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
8240: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
8250: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
8260: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
8270: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
8280: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
8290: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
82a0: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
82b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
82c0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
82d0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
82e0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
82f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8300: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
8310: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8320: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
8330: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8340: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
8350: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8360: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
8370: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8380: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
8390: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
83a0: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
83b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
83c0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
83d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
83e0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
83f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
8400: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
8410: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
8420: 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57  AP_UNDELETABLE_W
8430: 48 45 4e 5f 4f 50 45 4e 5d 0a 2a 2a 20 3c 6c 69  HEN_OPEN].** <li
8440: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
8450: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
8460: 49 54 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ITE].** <li> [SQ
8470: 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54  LITE_IOCAP_IMMUT
8480: 41 42 4c 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  ABLE].** </ul>.*
8490: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
84a0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
84b0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
84c0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
84d0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
84e0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
84f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
8500: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
8510: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
8520: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
8530: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
8540: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
8550: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
8560: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
8570: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
8580: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
8590: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
85a0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
85b0: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
85c0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
85d0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
85e0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
85f0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
8600: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
8610: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
8620: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
8630: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
8640: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
8650: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8660: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
8670: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
8680: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
8690: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
86a0: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
86b0: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
86c0: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
86d0: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
86e0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
86f0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
8700: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
8710: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
8720: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
8730: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
8740: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
8750: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
8760: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
8770: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
8780: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
8790: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
87a0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
87b0: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
87c0: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
87d0: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
87e0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
87f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
8800: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
8810: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
8820: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
8830: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
8840: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
8850: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
8860: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8870: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
8880: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
8890: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
88a0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
88b0: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
88c0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
88d0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
88e0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
88f0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
8900: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
8910: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8920: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
8930: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
8940: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8950: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
8960: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
8970: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
8980: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
8990: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
89a0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
89b0: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
89c0: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
89d0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
89e0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
89f0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
8a00: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
8a10: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
8a20: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
8a30: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8a40: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
8a50: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
8a60: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
8a70: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
8a80: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
8a90: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
8aa0: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
8ab0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8ac0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
8ad0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
8ae0: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
8af0: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
8b00: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
8b10: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
8b20: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
8b30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8b40: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
8b50: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
8b60: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
8b70: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
8b80: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8b90: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
8ba0: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
8bb0: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
8bc0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
8bd0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
8be0: 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 46 65  2 */.  int (*xFe
8bf0: 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  tch)(sqlite3_fil
8c00: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8c10: 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69 41 6d  4 iOfst, int iAm
8c20: 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b 0a 20  t, void **pp);. 
8c30: 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63 68 29   int (*xUnfetch)
8c40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8c50: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
8c60: 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b 0a 20  fst, void *p);. 
8c70: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
8c80: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
8c90: 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20 20 2f  version 3 */.  /
8ca0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
8cb0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
8cc0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
8cd0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
8ce0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
8cf0: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
8d00: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 20 4b 45 59  l Opcodes.** KEY
8d10: 57 4f 52 44 53 3a 20 7b 66 69 6c 65 20 63 6f 6e  WORDS: {file con
8d20: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 7d 20 7b 66  trol opcodes} {f
8d30: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
8d40: 64 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  de}.**.** These 
8d50: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
8d60: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
8d70: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
8d80: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
8d90: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
8da0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
8db0: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
8dc0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8dd0: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
8de0: 65 2e 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  e..**.** <ul>.**
8df0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8e00: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 5d 0a  NTL_LOCKSTATE]].
8e10: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8e20: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20  CNTL_LOCKSTATE] 
8e30: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66  opcode is used f
8e40: 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54  or debugging.  T
8e50: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61  his.** opcode ca
8e60: 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f  uses the xFileCo
8e70: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20  ntrol method to 
8e80: 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e  write the curren
8e90: 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68  t state of.** th
8ea0: 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b  e lock (one of [
8eb0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
8ec0: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
8ed0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c  SHARED],.** [SQL
8ee0: 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45  ITE_LOCK_RESERVE
8ef0: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  D], [SQLITE_LOCK
8f00: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53  _PENDING], or [S
8f10: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
8f20: 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61  SIVE]).** into a
8f30: 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74  n integer that t
8f40: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
8f50: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73   points to. This
8f60: 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
8f70: 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65  s used during te
8f80: 73 74 69 6e 67 20 61 6e 64 20 69 73 20 6f 6e 6c  sting and is onl
8f90: 79 20 61 76 61 69 6c 61 62 6c 65 20 77 68 65 6e  y available when
8fa0: 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 53 54   the SQLITE_TEST
8fb0: 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
8fc0: 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
8fd0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8fe0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
8ff0: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
9000: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9010: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
9020: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
9030: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
9040: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
9050: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
9060: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
9070: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
9080: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
9090: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
90a0: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
90b0: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
90c0: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
90d0: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
90e0: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
90f0: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
9100: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
9110: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
9120: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
9130: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
9140: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
9150: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
9160: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
9170: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
9180: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9190: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
91a0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
91b0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
91c0: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
91d0: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
91e0: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
91f0: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
9200: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
9210: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
9220: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
9230: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
9240: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
9250: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
9260: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9270: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
9280: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
9290: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
92a0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
92b0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
92c0: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
92d0: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
92e0: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
92f0: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
9300: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
9310: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
9320: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
9330: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
9340: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
9350: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
9360: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
9370: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
9380: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9390: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
93a0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
93b0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
93c0: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
93d0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
93e0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
93f0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
9400: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
9410: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
9420: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
9430: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
9440: 65 20 61 6c 73 6f 20 5b 53 51 4c 49 54 45 5f 46  e also [SQLITE_F
9450: 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50 4f 49  CNTL_JOURNAL_POI
9460: 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  NTER]..**.** <li
9470: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9480: 4a 4f 55 52 4e 41 4c 5f 50 4f 49 4e 54 45 52 5d  JOURNAL_POINTER]
9490: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
94a0: 5f 46 43 4e 54 4c 5f 4a 4f 55 52 4e 41 4c 5f 50  _FCNTL_JOURNAL_P
94b0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
94c0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
94d0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
94e0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
94f0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
9500: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6a  iated with the j
9510: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 28 65 69 74  ournal file (eit
9520: 68 65 72 0a 2a 2a 20 74 68 65 20 5b 72 6f 6c 6c  her.** the [roll
9530: 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 5d 20 6f 72  back journal] or
9540: 20 74 68 65 20 5b 77 72 69 74 65 2d 61 68 65 61   the [write-ahea
9550: 64 20 6c 6f 67 5d 29 20 66 6f 72 20 61 20 70 61  d log]) for a pa
9560: 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73  rticular databas
9570: 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
9580: 20 20 53 65 65 20 61 6c 73 6f 20 5b 53 51 4c 49    See also [SQLI
9590: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
95a0: 49 4e 54 45 52 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  INTER]..**.** <l
95b0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
95c0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a  _SYNC_OMITTED]].
95d0: 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20  ** No longer in 
95e0: 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  use..**.** <li>[
95f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9600: 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NC]].** The [SQL
9610: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20  ITE_FCNTL_SYNC] 
9620: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9630: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9640: 79 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20  y SQLite and.** 
9650: 73 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20  sent to the VFS 
9660: 69 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f  immediately befo
9670: 72 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74  re the xSync met
9680: 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  hod is invoked o
9690: 6e 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  n a.** database 
96a0: 66 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e  file descriptor.
96b0: 20 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e   Or, if the xSyn
96c0: 63 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20  c method is not 
96d0: 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61  invoked .** beca
96e0: 75 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73  use the user has
96f0: 20 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69   configured SQLi
9700: 74 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41  te with .** [PRA
9710: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20  GMA synchronous 
9720: 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f  | PRAGMA synchro
9730: 6e 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20  nous=OFF] it is 
9740: 69 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65  invoked in place
9750: 20 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e   .** of the xSyn
9760: 63 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73  c method. In mos
9770: 74 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69  t cases, the poi
9780: 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61  nter argument pa
9790: 73 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69  ssed with.** thi
97a0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
97b0: 73 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c  s NULL. However,
97c0: 20 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65   if the database
97d0: 20 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73   file is being s
97e0: 79 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74  ynced.** as part
97f0: 20 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61   of a multi-data
9800: 62 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65  base commit, the
9810: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73   argument points
9820: 20 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e   to a nul-termin
9830: 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63  ated.** string c
9840: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72  ontaining the tr
9850: 61 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65  ansactions maste
9860: 72 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e  r-journal file n
9870: 61 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20  ame. VFSes that 
9880: 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  .** do not need 
9890: 74 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75  this signal shou
98a0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
98b0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20  re this opcode. 
98c0: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a  Applications .**
98d0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
98e0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
98f0: 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74  ontrol()] with t
9900: 68 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f  his opcode as do
9910: 69 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64  ing so may .** d
9920: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
9930: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
9940: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68  ialized VFSes th
9950: 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74  at do require it
9960: 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  .  .**.** <li>[[
9970: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d  SQLITE_FCNTL_COM
9980: 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a  MIT_PHASETWO]].*
9990: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
99a0: 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45  NTL_COMMIT_PHASE
99b0: 54 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67  TWO] opcode is g
99c0: 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61  enerated interna
99d0: 6c 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  lly by SQLite.**
99e0: 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65   and sent to the
99f0: 20 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61   VFS after a tra
9a00: 6e 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65  nsaction has bee
9a10: 6e 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65  n committed imme
9a20: 64 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62  diately.** but b
9a30: 65 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61  efore the databa
9a40: 73 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20  se is unlocked. 
9a50: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  VFSes that do no
9a60: 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  t need this sign
9a70: 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c  al.** should sil
9a80: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9a90: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
9aa0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
9ab0: 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74  t call.** [sqlit
9ac0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
9ad0: 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63  )] with this opc
9ae0: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
9af0: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
9b00: 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66  .** operation of
9b10: 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64   the specialized
9b20: 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72   VFSes that do r
9b30: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
9b40: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
9b50: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
9b60: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
9b70: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
9b80: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
9b90: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
9ba0: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
9bb0: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
9bc0: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
9bd0: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
9be0: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
9bf0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
9c00: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
9c10: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
9c20: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
9c30: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
9c40: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
9c50: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
9c60: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
9c70: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
9c80: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
9c90: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
9ca0: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
9cb0: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
9cc0: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
9cd0: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
9ce0: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
9cf0: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
9d00: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
9d10: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
9d20: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
9d30: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
9d40: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
9d50: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9d60: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
9d70: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
9d80: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
9d90: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9da0: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
9db0: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
9dc0: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
9dd0: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
9de0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
9df0: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
9e00: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
9e10: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
9e20: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9e30: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
9e40: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9e50: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9e60: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9e70: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
9e80: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
9e90: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
9ea0: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
9eb0: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
9ec0: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9ed0: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9ee0: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
9ef0: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
9f00: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
9f10: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
9f20: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
9f30: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
9f40: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9f50: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9f60: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
9f70: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
9f80: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
9f90: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9fa0: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9fb0: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
9fc0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9fd0: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9fe0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9ff0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
a000: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
a010: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
a020: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
a030: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
a040: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
a050: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
a060: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
a070: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
a080: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
a090: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
a0a0: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
a0b0: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
a0c0: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
a0d0: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
a0e0: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
a0f0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
a100: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
a110: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
a120: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
a130: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
a140: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
a150: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
a160: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
a170: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
a180: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
a190: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
a1a0: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
a1b0: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
a1c0: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
a1d0: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
a1e0: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
a1f0: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
a200: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
a210: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
a220: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
a230: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
a240: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
a250: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
a260: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
a270: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
a280: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
a290: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
a2a0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
a2b0: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
a2c0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
a2d0: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
a2e0: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
a2f0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a300: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a310: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a320: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a330: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
a340: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
a350: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a360: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a370: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
a380: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
a390: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
a3a0: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
a3b0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
a3c0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
a3d0: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
a3e0: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
a3f0: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
a400: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
a410: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
a420: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
a430: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
a440: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
a450: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
a460: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
a470: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
a480: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
a490: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
a4a0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
a4b0: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
a4c0: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
a4d0: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
a4e0: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
a4f0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
a500: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
a510: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
a520: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
a530: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
a540: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
a550: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
a560: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
a570: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
a580: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
a590: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a5a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a5b0: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
a5c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
a5d0: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
a5e0: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
a5f0: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
a600: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
a610: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
a620: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
a630: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
a640: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
a650: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
a660: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
a670: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
a680: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
a690: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
a6a0: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
a6b0: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
a6c0: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
a6d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a6e0: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
a6f0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a700: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
a710: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
a720: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
a730: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
a740: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
a750: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
a760: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
a770: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
a780: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
a790: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
a7a0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
a7b0: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
a7c0: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
a7d0: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
a7e0: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
a7f0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
a800: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
a810: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
a820: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
a830: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
a840: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
a850: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
a860: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
a870: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
a880: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
a890: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
a8a0: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
a8b0: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
a8c0: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
a8d0: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
a8e0: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
a8f0: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
a900: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
a910: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
a920: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
a930: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
a940: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
a950: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
a960: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
a970: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
a980: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
a990: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
a9a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
a9b0: 46 53 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  FS_POINTER]].** 
a9c0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a9d0: 54 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 5d 20  TL_VFS_POINTER] 
a9e0: 6f 70 63 6f 64 65 20 66 69 6e 64 73 20 61 20 70  opcode finds a p
a9f0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 74 6f  ointer to the to
aa00: 70 2d 6c 65 76 65 6c 0a 2a 2a 20 5b 56 46 53 65  p-level.** [VFSe
aa10: 73 5d 20 63 75 72 72 65 6e 74 6c 79 20 69 6e 20  s] currently in 
aa20: 75 73 65 2e 20 20 5e 28 54 68 65 20 61 72 67 75  use.  ^(The argu
aa30: 6d 65 6e 74 20 58 20 69 6e 0a 2a 2a 20 73 71 6c  ment X in.** sql
aa40: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
aa50: 6c 28 64 62 2c 53 51 4c 49 54 45 5f 46 43 4e 54  l(db,SQLITE_FCNT
aa60: 4c 5f 56 46 53 5f 50 4f 49 4e 54 45 52 2c 58 29  L_VFS_POINTER,X)
aa70: 20 6d 75 73 74 20 62 65 0a 2a 2a 20 6f 66 20 74   must be.** of t
aa80: 79 70 65 20 22 5b 73 71 6c 69 74 65 33 5f 76 66  ype "[sqlite3_vf
aa90: 73 5d 20 2a 2a 22 2e 20 20 54 68 69 73 20 6f 70  s] **".  This op
aaa0: 63 6f 64 65 73 20 77 69 6c 6c 20 73 65 74 20 2a  codes will set *
aab0: 58 0a 2a 2a 20 74 6f 20 61 20 70 6f 69 6e 74 65  X.** to a pointe
aac0: 72 20 74 6f 20 74 68 65 20 74 6f 70 2d 6c 65 76  r to the top-lev
aad0: 65 6c 20 56 46 53 2e 29 5e 0a 2a 2a 20 5e 57 68  el VFS.)^.** ^Wh
aae0: 65 6e 20 74 68 65 72 65 20 61 72 65 20 6d 75 6c  en there are mul
aaf0: 74 69 70 6c 65 20 56 46 53 20 73 68 69 6d 73 20  tiple VFS shims 
ab00: 69 6e 20 74 68 65 20 73 74 61 63 6b 2c 20 74 68  in the stack, th
ab10: 69 73 20 6f 70 63 6f 64 65 20 66 69 6e 64 73 20  is opcode finds 
ab20: 74 68 65 0a 2a 2a 20 75 70 70 65 72 2d 6d 6f 73  the.** upper-mos
ab30: 74 20 73 68 69 6d 20 6f 6e 6c 79 2e 0a 2a 2a 0a  t shim only..**.
ab40: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ab50: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a  FCNTL_PRAGMA]].*
ab60: 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50  * ^Whenever a [P
ab70: 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74  RAGMA] statement
ab80: 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b   is parsed, an [
ab90: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
aba0: 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f  GMA] .** file co
abb0: 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f  ntrol is sent to
abc0: 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74   the open [sqlit
abd0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
abe0: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
abf0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
ac00: 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74   file to which t
ac10: 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  he pragma statem
ac20: 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65  ent refers. ^The
ac30: 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
ac40: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
ac50: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
ac60: 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72  ontrol is an arr
ac70: 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72  ay of.** pointer
ac80: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68  s to strings (ch
ac90: 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74  ar**) in which t
aca0: 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e  he second elemen
acb0: 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a  t of the array.*
acc0: 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
acd0: 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20   the pragma and 
ace0: 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e  the third elemen
acf0: 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e  t is the argumen
ad00: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67  t to the.** prag
ad10: 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  ma or NULL if th
ad20: 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20  e pragma has no 
ad30: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20  argument.  ^The 
ad40: 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a  handler for an.*
ad50: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
ad60: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
ad70: 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61  trol can optiona
ad80: 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72  lly make the fir
ad90: 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66  st element.** of
ada0: 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75   the char** argu
adb0: 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20  ment point to a 
adc0: 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20  string obtained 
add0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
ade0: 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74  rintf()].** or t
adf0: 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  he equivalent an
ae00: 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77 69  d that string wi
ae10: 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65  ll become the re
ae20: 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67  sult of the prag
ae30: 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72  ma or.** the err
ae40: 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74 68  or message if th
ae50: 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20  e pragma fails. 
ae60: 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
ae70: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
ae80: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
ae90: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f  turns [SQLITE_NO
aea0: 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f  TFOUND], then no
aeb0: 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41  rmal .** [PRAGMA
aec0: 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e  ] processing con
aed0: 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65  tinues.  ^If the
aee0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
aef0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
af00: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
af10: 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e  SQLITE_OK], then
af20: 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73 75   the parser assu
af30: 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  mes that the.** 
af40: 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20  VFS has handled 
af50: 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c  the PRAGMA itsel
af60: 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65 72  f and the parser
af70: 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d   generates a no-
af80: 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  op.** prepared s
af90: 74 61 74 65 6d 65 6e 74 20 69 66 20 72 65 73 75  tatement if resu
afa0: 6c 74 20 73 74 72 69 6e 67 20 69 73 20 4e 55 4c  lt string is NUL
afb0: 4c 2c 20 6f 72 20 74 68 61 74 20 72 65 74 75 72  L, or that retur
afc0: 6e 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  ns a copy.** of 
afd0: 74 68 65 20 72 65 73 75 6c 74 20 73 74 72 69 6e  the result strin
afe0: 67 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20  g if the string 
aff0: 69 73 20 6e 6f 6e 2d 4e 55 4c 4c 2e 0a 2a 2a 20  is non-NULL..** 
b000: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
b010: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
b020: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
b030: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
b040: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
b050: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
b060: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
b070: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
b080: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
b090: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
b0a0: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
b0b0: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
b0c0: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
b0d0: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
b0e0: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
b0f0: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
b100: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
b110: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
b120: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
b130: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
b140: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
b150: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
b160: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
b170: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
b180: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
b190: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c  tements..**.** <
b1a0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b1b0: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a  L_BUSYHANDLER]].
b1c0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
b1d0: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
b1e0: 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72  R].** file-contr
b1f0: 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ol may be invoke
b200: 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74  d by SQLite on t
b210: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
b220: 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74   handle.** short
b230: 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20 6f  ly after it is o
b240: 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  pened in order t
b250: 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73 74  o provide a cust
b260: 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63 65  om VFS with acce
b270: 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e  ss.** to the con
b280: 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61  nections busy-ha
b290: 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20  ndler callback. 
b2a0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
b2b0: 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a  of type (void **
b2c0: 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20  ).** - an array 
b2d0: 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20  of two (void *) 
b2e0: 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73  values. The firs
b2f0: 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61  t (void *) actua
b300: 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f  lly points.** to
b310: 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74   a function of t
b320: 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69  ype (int (*)(voi
b330: 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20  d *)). In order 
b340: 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f  to invoke the co
b350: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73  nnections.** bus
b360: 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20  y-handler, this 
b370: 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  function should 
b380: 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
b390: 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64  the second (void
b3a0: 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72   *) in.** the ar
b3b0: 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ray as the only 
b3c0: 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20  argument. If it 
b3d0: 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
b3e0: 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61  , then the opera
b3f0: 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
b400: 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69 74  e retried. If it
b410: 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
b420: 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68  he custom VFS sh
b430: 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65  ould abandon the
b440: 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72  .** current oper
b450: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
b460: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b470: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a  TEMPFILENAME]].*
b480: 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63  * ^Application c
b490: 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53  an invoke the [S
b4a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b4b0: 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63  FILENAME] file-c
b4c0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76  ontrol.** to hav
b4d0: 65 20 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74  e SQLite generat
b4e0: 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79  e a.** temporary
b4f0: 20 66 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20   filename using 
b500: 74 68 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74  the same algorit
b510: 68 6d 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f  hm that is follo
b520: 77 65 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a  wed to generate.
b530: 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
b540: 65 6e 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20  enames for TEMP 
b550: 74 61 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72  tables and other
b560: 20 69 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20   internal uses. 
b570: 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74   The.** argument
b580: 20 73 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61   should be a cha
b590: 72 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62  r** which will b
b5a0: 65 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  e filled with th
b5b0: 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72  e filename.** wr
b5c0: 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72  itten into memor
b5d0: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
b5e0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
b5f0: 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20  )].  The caller 
b600: 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65  should.** invoke
b610: 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
b620: 5d 20 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20  ] on the result 
b630: 74 6f 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72  to avoid a memor
b640: 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  y leak..**.** <l
b650: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
b660: 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  _MMAP_SIZE]].** 
b670: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b680: 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c  L_MMAP_SIZE] fil
b690: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e control is use
b6a0: 64 20 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65  d to query or se
b6b0: 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d  t the.** maximum
b6c0: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
b6d0: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73   that will be us
b6e0: 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61  ed for memory-ma
b6f0: 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65  pped I/O..** The
b700: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
b710: 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75  ointer to a valu
b720: 65 20 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65  e of type sqlite
b730: 33 5f 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20  3_int64 that.** 
b740: 69 73 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d  is an advisory m
b750: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
b760: 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69   bytes in the fi
b770: 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70  le to memory map
b780: 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  .  The.** pointe
b790: 72 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e  r is overwritten
b7a0: 20 77 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61   with the old va
b7b0: 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20  lue.  The limit 
b7c0: 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69  is not changed i
b7d0: 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f  f.** the value o
b7e0: 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65  riginally pointe
b7f0: 64 20 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65  d to is negative
b800: 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72  , and so the cur
b810: 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63  rent limit .** c
b820: 61 6e 20 62 65 20 71 75 65 72 69 65 64 20 62 79  an be queried by
b830: 20 70 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f   passing in a po
b840: 69 6e 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74  inter to a negat
b850: 69 76 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69  ive number.  Thi
b860: 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  s.** file-contro
b870: 6c 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e  l is used intern
b880: 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  ally to implemen
b890: 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73  t [PRAGMA mmap_s
b8a0: 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ize]..**.** <li>
b8b0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  [[SQLITE_FCNTL_T
b8c0: 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  RACE]].** The [S
b8d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43  QLITE_FCNTL_TRAC
b8e0: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
b8f0: 70 72 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72  provides advisor
b900: 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  y information.**
b910: 20 74 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75   to the VFS abou
b920: 74 20 77 68 61 74 20 74 68 65 20 68 69 67 68 65  t what the highe
b930: 72 20 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20  r layers of the 
b940: 53 51 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65  SQLite stack are
b950: 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20   doing..** This 
b960: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
b970: 75 73 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53  used by some VFS
b980: 20 61 63 74 69 76 69 74 79 20 74 72 61 63 69 6e   activity tracin
b990: 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68  g [shims]..** Th
b9a0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
b9b0: 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
b9c0: 73 74 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20  string.  Higher 
b9d0: 6c 61 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a  layers in the.**
b9e0: 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61   SQLite stack ma
b9f0: 79 20 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61  y generate insta
ba00: 6e 63 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c  nces of this fil
ba10: 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20  e control if.** 
ba20: 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
ba30: 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d  FCNTL_TRACE] com
ba40: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
ba50: 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
ba60: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ba70: 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d  FCNTL_HAS_MOVED]
ba80: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
ba90: 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44  _FCNTL_HAS_MOVED
baa0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
bab0: 6e 74 65 72 70 72 65 74 73 20 69 74 73 20 61 72  nterprets its ar
bac0: 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70  gument as a.** p
bad0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
bae0: 65 67 65 72 20 61 6e 64 20 69 74 20 77 72 69 74  eger and it writ
baf0: 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74  es a boolean int
bb00: 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 20 64  o that integer d
bb10: 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77  epending.** on w
bb20: 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
bb30: 65 20 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20  e file has been 
bb40: 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20  renamed, moved, 
bb50: 6f 72 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65  or deleted since
bb60: 20 69 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74   it.** was first
bb70: 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c   opened..**.** <
bb80: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bb90: 4c 5f 57 49 4e 33 32 5f 47 45 54 5f 48 41 4e 44  L_WIN32_GET_HAND
bba0: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
bbb0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
bbc0: 47 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  GET_HANDLE] opco
bbd0: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
bbe0: 6f 20 6f 62 74 61 69 6e 20 74 68 65 0a 2a 2a 20  o obtain the.** 
bbf0: 75 6e 64 65 72 6c 79 69 6e 67 20 6e 61 74 69 76  underlying nativ
bc00: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 61 73  e file handle as
bc10: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
bc20: 66 69 6c 65 20 68 61 6e 64 6c 65 2e 20 20 54 68  file handle.  Th
bc30: 69 73 20 66 69 6c 65 0a 2a 2a 20 63 6f 6e 74 72  is file.** contr
bc40: 6f 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74  ol interprets it
bc50: 73 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 20  s argument as a 
bc60: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 61 74  pointer to a nat
bc70: 69 76 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20  ive file handle 
bc80: 61 6e 64 0a 2a 2a 20 77 72 69 74 65 73 20 74 68  and.** writes th
bc90: 65 20 72 65 73 75 6c 74 69 6e 67 20 76 61 6c 75  e resulting valu
bca0: 65 20 74 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 3c  e there..**.** <
bcb0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
bcc0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
bcd0: 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  LE]].** The [SQL
bce0: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
bcf0: 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f  SET_HANDLE] opco
bd00: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
bd10: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
bd20: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
bd30: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
bd40: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70  l method to swap
bd50: 20 74 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65   the file handle
bd60: 20 77 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a   with the one.**
bd70: 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
bd80: 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74  he pArg argument
bd90: 2e 20 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  .  This capabili
bda0: 74 79 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ty is used durin
bdb0: 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64  g testing.** and
bdc0: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
bdd0: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
bde0: 20 53 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20   SQLITE_TEST is 
bdf0: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
be00: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
be10: 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 5d 0a 2a 2a  L_WAL_BLOCK]].**
be20: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
be30: 54 4c 5f 57 41 4c 5f 42 4c 4f 43 4b 5d 20 69 73  TL_WAL_BLOCK] is
be40: 20 61 20 73 69 67 6e 61 6c 20 74 6f 20 74 68 65   a signal to the
be50: 20 56 46 53 20 6c 61 79 65 72 20 74 68 61 74 20   VFS layer that 
be60: 69 74 20 6d 69 67 68 74 0a 2a 2a 20 62 65 20 61  it might.** be a
be70: 64 76 61 6e 74 61 67 65 6f 75 73 20 74 6f 20 62  dvantageous to b
be80: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 6e 65 78 74  lock on the next
be90: 20 57 41 4c 20 6c 6f 63 6b 20 69 66 20 74 68 65   WAL lock if the
bea0: 20 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 69 6d 6d   lock is not imm
beb0: 65 64 69 61 74 65 6c 79 0a 2a 2a 20 61 76 61 69  ediately.** avai
bec0: 6c 61 62 6c 65 2e 20 20 54 68 65 20 57 41 4c 20  lable.  The WAL 
bed0: 73 75 62 73 79 73 74 65 6d 20 69 73 73 75 65 73  subsystem issues
bee0: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 64 75 72   this signal dur
bef0: 69 6e 67 20 72 61 72 65 0a 2a 2a 20 63 69 72 63  ing rare.** circ
bf00: 75 6d 73 74 61 6e 63 65 73 20 69 6e 20 6f 72 64  umstances in ord
bf10: 65 72 20 74 6f 20 66 69 78 20 61 20 70 72 6f 62  er to fix a prob
bf20: 6c 65 6d 20 77 69 74 68 20 70 72 69 6f 72 69 74  lem with priorit
bf30: 79 20 69 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20  y inversion..** 
bf40: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
bf50: 75 6c 64 20 3c 65 6d 3e 6e 6f 74 3c 2f 65 6d 3e  uld <em>not</em>
bf60: 20 75 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63   use this file-c
bf70: 6f 6e 74 72 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ontrol..**.** <l
bf80: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
bf90: 5f 5a 49 50 56 46 53 5d 5d 0a 2a 2a 20 54 68 65  _ZIPVFS]].** The
bfa0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a   [SQLITE_FCNTL_Z
bfb0: 49 50 56 46 53 5d 20 6f 70 63 6f 64 65 20 69 73  IPVFS] opcode is
bfc0: 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20   implemented by 
bfd0: 7a 69 70 76 66 73 20 6f 6e 6c 79 2e 20 41 6c 6c  zipvfs only. All
bfe0: 20 6f 74 68 65 72 0a 2a 2a 20 56 46 53 20 73 68   other.** VFS sh
bff0: 6f 75 6c 64 20 72 65 74 75 72 6e 20 53 51 4c 49  ould return SQLI
c000: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66 6f 72 20  TE_NOTFOUND for 
c010: 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 0a  this opcode..**.
c020: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
c030: 46 43 4e 54 4c 5f 52 42 55 5d 5d 0a 2a 2a 20 54  FCNTL_RBU]].** T
c040: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
c050: 5f 52 42 55 5d 20 6f 70 63 6f 64 65 20 69 73 20  _RBU] opcode is 
c060: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 62 79 20 74  implemented by t
c070: 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 75  he special VFS u
c080: 73 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 52 42  sed by.** the RB
c090: 55 20 65 78 74 65 6e 73 69 6f 6e 20 6f 6e 6c 79  U extension only
c0a0: 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 56 46 53  .  All other VFS
c0b0: 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 53   should return S
c0c0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 66  QLITE_NOTFOUND f
c0d0: 6f 72 0a 2a 2a 20 74 68 69 73 20 6f 70 63 6f 64  or.** this opcod
c0e0: 65 2e 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  e.  .** </ul>.*/
c0f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c100: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
c110: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
c120: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c130: 43 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f  CNTL_GET_LOCKPRO
c140: 58 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23  XYFILE       2.#
c150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c160: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
c170: 59 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64  YFILE       3.#d
c180: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c190: 54 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20  TL_LAST_ERRNO   
c1a0: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
c1b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c1c0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20  L_SIZE_HINT     
c1d0: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
c1e0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c1f0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
c200: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
c210: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c220: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
c230: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
c240: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
c250: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
c260: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
c270: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
c280: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20  N32_AV_RETRY    
c290: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
c2a0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
c2b0: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20  SIST_WAL        
c2c0: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
c2d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
c2e0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
c2f0: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
c300: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
c310: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ME              
c320: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
c330: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
c340: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
c350: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   13.#define SQLI
c360: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20  TE_FCNTL_PRAGMA 
c370: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c380: 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  14.#define SQLIT
c390: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
c3a0: 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31  LER            1
c3b0: 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
c3c0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
c3d0: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36  AME           16
c3e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c3f0: 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20  FCNTL_MMAP_SIZE 
c400: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a               18.
c410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
c420: 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20  CNTL_TRACE      
c430: 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23              19.#
c440: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
c450: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20  NTL_HAS_MOVED   
c460: 20 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64             20.#d
c470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
c480: 54 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20  TL_SYNC         
c490: 20 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65            21.#de
c4a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
c4b0: 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57  L_COMMIT_PHASETW
c4c0: 4f 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66  O        22.#def
c4d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
c4e0: 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c  _WIN32_SET_HANDL
c4f0: 45 20 20 20 20 20 20 20 32 33 0a 23 64 65 66 69  E       23.#defi
c500: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
c510: 57 41 4c 5f 42 4c 4f 43 4b 20 20 20 20 20 20 20  WAL_BLOCK       
c520: 20 20 20 20 20 20 20 32 34 0a 23 64 65 66 69 6e         24.#defin
c530: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 5a  e SQLITE_FCNTL_Z
c540: 49 50 56 46 53 20 20 20 20 20 20 20 20 20 20 20  IPVFS           
c550: 20 20 20 20 20 20 32 35 0a 23 64 65 66 69 6e 65        25.#define
c560: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 52 42   SQLITE_FCNTL_RB
c570: 55 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  U               
c580: 20 20 20 20 20 32 36 0a 23 64 65 66 69 6e 65 20       26.#define 
c590: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
c5a0: 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20  _POINTER        
c5b0: 20 20 20 20 32 37 0a 23 64 65 66 69 6e 65 20 53      27.#define S
c5c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4a 4f 55 52  QLITE_FCNTL_JOUR
c5d0: 4e 41 4c 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  NAL_POINTER     
c5e0: 20 20 20 32 38 0a 23 64 65 66 69 6e 65 20 53 51     28.#define SQ
c5f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
c600: 5f 47 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _GET_HANDLE     
c610: 20 20 32 39 0a 23 64 65 66 69 6e 65 20 53 51 4c    29.#define SQL
c620: 49 54 45 5f 46 43 4e 54 4c 5f 50 44 42 20 20 20  ITE_FCNTL_PDB   
c630: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
c640: 20 33 30 0a 0a 2f 2a 20 64 65 70 72 65 63 61 74   30../* deprecat
c650: 65 64 20 6e 61 6d 65 73 20 2a 2f 0a 23 64 65 66  ed names */.#def
c660: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
c670: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
c680: 20 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 47    SQLITE_FCNTL_G
c690: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
c6a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
c6b0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
c6c0: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
c6d0: 4e 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_SET_LOCKPROX
c6e0: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
c6f0: 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20  LITE_LAST_ERRNO 
c700: 20 20 20 20 20 20 20 20 20 20 20 20 53 51 4c 49              SQLI
c710: 54 45 5f 46 43 4e 54 4c 5f 4c 41 53 54 5f 45 52  TE_FCNTL_LAST_ER
c720: 52 4e 4f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  RNO.../*.** CAPI
c730: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
c740: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
c750: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
c760: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
c770: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
c780: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
c790: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
c7a0: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
c7b0: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
c7c0: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
c7d0: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
c7e0: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
c7f0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
c800: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
c810: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
c820: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
c830: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
c840: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
c850: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
c860: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
c870: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
c880: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
c890: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
c8a0: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
c8b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64  * CAPI3REF: Load
c8c0: 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 54  able Extension T
c8d0: 68 75 6e 6b 0a 2a 2a 0a 2a 2a 20 41 20 70 6f 69  hunk.**.** A poi
c8e0: 6e 74 65 72 20 74 6f 20 74 68 65 20 6f 70 61 71  nter to the opaq
c8f0: 75 65 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ue sqlite3_api_r
c900: 6f 75 74 69 6e 65 73 20 73 74 72 75 63 74 75 72  outines structur
c910: 65 20 69 73 20 70 61 73 73 65 64 20 61 73 0a 2a  e is passed as.*
c920: 2a 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  * the third para
c930: 6d 65 74 65 72 20 74 6f 20 65 6e 74 72 79 20 70  meter to entry p
c940: 6f 69 6e 74 73 20 6f 66 20 5b 6c 6f 61 64 61 62  oints of [loadab
c950: 6c 65 20 65 78 74 65 6e 73 69 6f 6e 73 5d 2e 20  le extensions]. 
c960: 20 54 68 69 73 0a 2a 2a 20 73 74 72 75 63 74 75   This.** structu
c970: 72 65 20 6d 75 73 74 20 62 65 20 74 79 70 65 64  re must be typed
c980: 65 66 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  efed in order to
c990: 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 63 6f 6d   work around com
c9a0: 70 69 6c 65 72 20 77 61 72 6e 69 6e 67 73 0a 2a  piler warnings.*
c9b0: 2a 20 6f 6e 20 73 6f 6d 65 20 70 6c 61 74 66 6f  * on some platfo
c9c0: 72 6d 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  rms..*/.typedef 
c9d0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 61  struct sqlite3_a
c9e0: 70 69 5f 72 6f 75 74 69 6e 65 73 20 73 71 6c 69  pi_routines sqli
c9f0: 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73  te3_api_routines
ca00: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ca10: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
ca20: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
ca30: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
ca40: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
ca50: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
ca60: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
ca70: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
ca80: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
ca90: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
caa0: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
cab0: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
cac0: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
cad0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
cae0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
caf0: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
cb00: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
cb10: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
cb20: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
cb30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
cb40: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
cb50: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
cb60: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
cb70: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
cb80: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
cb90: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
cba0: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
cbb0: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
cbc0: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
cbd0: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
cbe0: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
cbf0: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
cc00: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
cc10: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
cc20: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
cc30: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
cc40: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
cc50: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
cc60: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
cc70: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
cc80: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
cc90: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
cca0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
ccb0: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
ccc0: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
ccd0: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
cce0: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
ccf0: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
cd00: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
cd10: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
cd20: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
cd30: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
cd40: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
cd50: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
cd60: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
cd70: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
cd80: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
cd90: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
cda0: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
cdb0: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
cdc0: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
cdd0: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
cde0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
cdf0: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
ce00: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
ce10: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
ce20: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
ce30: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
ce40: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
ce50: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
ce60: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
ce70: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
ce80: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
ce90: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
cea0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
ceb0: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
cec0: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
ced0: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
cee0: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
cef0: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
cf00: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
cf10: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
cf20: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
cf30: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
cf40: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
cf50: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
cf60: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
cf70: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
cf80: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
cf90: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
cfa0: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
cfb0: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
cfc0: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
cfd0: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
cfe0: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
cff0: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
d000: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
d010: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
d020: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
d030: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
d040: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
d050: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
d060: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
d070: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
d080: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
d090: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
d0a0: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
d0b0: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
d0c0: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
d0d0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
d0e0: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
d0f0: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
d100: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
d110: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
d120: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
d130: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
d140: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
d150: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
d160: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
d170: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
d180: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
d190: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
d1a0: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
d1b0: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
d1c0: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
d1d0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
d1e0: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
d1f0: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
d200: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
d210: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
d220: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
d230: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
d240: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
d250: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
d260: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
d270: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
d280: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
d290: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
d2a0: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
d2b0: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
d2c0: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
d2d0: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
d2e0: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
d2f0: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
d300: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
d310: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
d320: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
d330: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
d340: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
d350: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
d360: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
d370: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
d380: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
d390: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
d3a0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
d3b0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
d3c0: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
d3d0: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
d3e0: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
d3f0: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
d400: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
d410: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
d420: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
d430: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
d440: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
d450: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
d460: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
d470: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
d480: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
d490: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
d4a0: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
d4b0: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
d4c0: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
d4d0: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
d4e0: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
d4f0: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
d500: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
d510: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
d520: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
d530: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
d540: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
d550: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
d560: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
d570: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
d580: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
d590: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
d5a0: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
d5b0: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
d5c0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
d5d0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
d5e0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
d5f0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
d600: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
d610: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
d620: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d630: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
d640: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
d650: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
d660: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
d670: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
d680: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
d690: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
d6a0: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
d6b0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
d6c0: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
d6d0: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
d6e0: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
d6f0: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
d700: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
d710: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
d720: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
d730: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
d740: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
d750: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
d760: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
d770: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
d780: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
d790: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
d7a0: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
d7b0: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
d7c0: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
d7d0: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
d7e0: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
d7f0: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
d800: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
d810: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
d820: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
d830: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
d840: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
d850: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
d860: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
d870: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
d880: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
d890: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
d8a0: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
d8b0: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
d8c0: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
d8d0: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
d8e0: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
d8f0: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
d900: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
d910: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
d920: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
d930: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
d940: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
d950: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
d960: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
d970: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
d980: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
d990: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
d9a0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
d9b0: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
d9c0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
d9d0: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
d9e0: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
d9f0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
da00: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
da10: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
da20: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
da30: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
da40: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
da50: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
da60: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
da70: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
da80: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
da90: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
daa0: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
dab0: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
dac0: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
dad0: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
dae0: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
daf0: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
db00: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
db10: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
db20: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
db30: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
db40: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
db50: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
db60: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
db70: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
db80: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
db90: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
dba0: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
dbb0: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
dbc0: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
dbd0: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
dbe0: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
dbf0: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
dc00: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
dc10: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
dc20: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
dc30: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
dc40: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
dc50: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
dc60: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
dc70: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
dc80: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
dc90: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
dca0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
dcb0: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
dcc0: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
dcd0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
dce0: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
dcf0: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
dd00: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
dd10: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
dd20: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
dd30: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
dd40: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
dd50: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
dd60: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
dd70: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
dd80: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
dd90: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
dda0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
ddb0: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
ddc0: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
ddd0: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
dde0: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
ddf0: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
de00: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
de10: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
de20: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
de30: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
de40: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
de50: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
de60: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
de70: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
de80: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
de90: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
dea0: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
deb0: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
dec0: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
ded0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
dee0: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
def0: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
df00: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
df10: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
df20: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
df30: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
df40: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
df50: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
df60: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
df70: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
df80: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
df90: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
dfa0: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
dfb0: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
dfc0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
dfd0: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
dfe0: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
dff0: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
e000: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
e010: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
e020: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
e030: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
e040: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
e050: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
e060: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
e070: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
e080: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
e090: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
e0a0: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
e0b0: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
e0c0: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
e0d0: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
e0e0: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
e0f0: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
e100: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
e110: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
e120: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
e130: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
e140: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
e150: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
e160: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
e170: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
e180: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
e190: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
e1a0: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
e1b0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
e1c0: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
e1d0: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
e1e0: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
e1f0: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
e200: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
e210: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
e220: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
e230: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
e240: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
e250: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
e260: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
e270: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
e280: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
e290: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
e2a0: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
e2b0: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
e2c0: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
e2d0: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
e2e0: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
e2f0: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
e300: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
e310: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
e320: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
e330: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
e340: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
e350: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
e360: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
e370: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
e380: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
e390: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
e3a0: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
e3b0: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
e3c0: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
e3d0: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
e3e0: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
e3f0: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
e400: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
e410: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
e420: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
e430: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
e440: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
e450: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
e460: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
e470: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
e480: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
e490: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
e4a0: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
e4b0: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
e4c0: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
e4d0: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
e4e0: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
e4f0: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
e500: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
e510: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
e520: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
e530: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
e540: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
e550: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
e560: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
e570: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
e580: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
e590: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
e5a0: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
e5b0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
e5c0: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
e5d0: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
e5e0: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
e5f0: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
e600: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
e610: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
e620: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
e630: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
e640: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
e650: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
e660: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
e670: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
e680: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
e690: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
e6a0: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
e6b0: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
e6c0: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
e6d0: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
e6e0: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
e6f0: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
e700: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
e710: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
e720: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
e730: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
e740: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
e750: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
e760: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
e770: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
e780: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
e790: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
e7a0: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
e7b0: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
e7c0: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
e7d0: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
e7e0: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
e7f0: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
e800: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
e810: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
e820: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
e830: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
e840: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
e850: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
e860: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
e870: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
e880: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
e890: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
e8a0: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
e8b0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
e8c0: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
e8d0: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
e8e0: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
e8f0: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
e900: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
e910: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
e920: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
e930: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
e940: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
e950: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
e960: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
e970: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
e980: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
e990: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
e9a0: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
e9b0: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
e9c0: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
e9d0: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
e9e0: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
e9f0: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
ea00: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
ea10: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ea20: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
ea30: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
ea40: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
ea50: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
ea60: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
ea70: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
ea80: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
ea90: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
eaa0: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
eab0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
eac0: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
ead0: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
eae0: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
eaf0: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
eb00: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
eb10: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
eb20: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
eb30: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
eb40: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
eb50: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
eb60: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
eb70: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
eb80: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
eb90: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
eba0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ebb0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
ebc0: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
ebd0: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
ebe0: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
ebf0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ec00: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
ec10: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
ec20: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
ec30: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
ec40: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
ec50: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
ec60: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
ec70: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
ec80: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
ec90: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
eca0: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
ecb0: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
ecc0: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
ecd0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
ece0: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
ecf0: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
ed00: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
ed10: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
ed20: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
ed30: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
ed40: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
ed50: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
ed60: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
ed70: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
ed80: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
ed90: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
eda0: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
edb0: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
edc0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
edd0: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
ede0: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
edf0: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
ee00: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
ee10: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
ee20: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
ee30: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
ee40: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
ee50: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
ee60: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
ee70: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
ee80: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
ee90: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
eea0: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
eeb0: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
eec0: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
eed0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
eee0: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
eef0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
ef00: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
ef10: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
ef20: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
ef30: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
ef40: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
ef50: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ef60: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
ef70: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
ef80: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
ef90: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
efa0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
efb0: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
efc0: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
efd0: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
efe0: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
eff0: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
f000: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
f010: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
f020: 65 64 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ed in future ver
f030: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
f040: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
f050: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
f060: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
f070: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
f080: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f090: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
f0a0: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
f0b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
f0c0: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
f0d0: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
f0e0: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
f0f0: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
f100: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
f110: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
f120: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
f130: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
f140: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
f150: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
f160: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
f170: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
f180: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
f190: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
f1a0: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
f1b0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
f1c0: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
f1d0: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
f1e0: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
f1f0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
f200: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
f210: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
f220: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
f230: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
f240: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
f250: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
f260: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
f270: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
f280: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
f290: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
f2a0: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
f2b0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
f2c0: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
f2d0: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
f2e0: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
f2f0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
f300: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
f310: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
f320: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
f330: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
f340: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
f350: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
f360: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
f370: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
f380: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
f390: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
f3a0: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
f3b0: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
f3c0: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
f3d0: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
f3e0: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
f3f0: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
f400: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
f410: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f420: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
f430: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
f440: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
f450: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
f460: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
f470: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
f480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
f490: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
f4a0: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
f4b0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
f4c0: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
f4d0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
f4e0: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
f4f0: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
f500: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
f510: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
f520: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
f530: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
f540: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
f550: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
f560: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
f570: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
f580: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
f590: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
f5a0: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
f5b0: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
f5c0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
f5d0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
f5e0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
f5f0: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
f600: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
f610: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
f620: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
f630: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
f640: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
f650: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
f660: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
f670: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
f680: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
f690: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
f6a0: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
f6b0: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
f6c0: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
f6d0: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
f6e0: 20 67 69 76 65 6e 20 6f 6e 20 74 68 65 20 63 6f   given on the co
f6f0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
f700: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
f710: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
f720: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
f730: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
f740: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
f750: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
f760: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
f770: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
f780: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
f790: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
f7a0: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
f7b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
f7c0: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
f7d0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
f7e0: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
f7f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
f800: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
f810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
f820: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
f830: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
f840: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
f850: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
f860: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
f870: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
f880: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
f890: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
f8a0: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
f8b0: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
f8c0: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
f8d0: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
f8e0: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
f8f0: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
f900: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
f910: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
f920: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
f930: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
f940: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
f950: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
f960: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
f970: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
f980: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
f990: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
f9a0: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
f9b0: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
f9c0: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
f9d0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
f9e0: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
f9f0: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
fa00: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
fa10: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
fa20: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
fa30: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
fa40: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
fa50: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
fa60: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
fa70: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
fa80: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
fa90: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
faa0: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
fab0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
fac0: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
fad0: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
fae0: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
faf0: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
fb00: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
fb10: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
fb20: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
fb30: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
fb40: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
fb50: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
fb60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fb70: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
fb80: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
fb90: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
fba0: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
fbb0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
fbc0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
fbd0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
fbe0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
fbf0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
fc00: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
fc10: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
fc20: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
fc30: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
fc40: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
fc50: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
fc60: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
fc70: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
fc80: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
fc90: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
fca0: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
fcb0: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
fcc0: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
fcd0: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
fce0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
fcf0: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
fd00: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
fd10: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
fd20: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
fd30: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
fd40: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
fd50: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
fd60: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
fd70: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
fd80: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
fd90: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
fda0: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
fdb0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fdc0: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
fdd0: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
fde0: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
fdf0: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
fe00: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
fe10: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
fe20: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
fe30: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
fe40: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
fe50: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
fe60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
fe70: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
fe80: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
fe90: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
fea0: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
feb0: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
fec0: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
fed0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
fee0: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
fef0: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
ff00: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
ff10: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
ff20: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
ff30: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
ff40: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
ff50: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
ff60: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
ff70: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
ff80: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ff90: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
ffa0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
ffb0: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
ffc0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
ffd0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ffe0: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
fff0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
10000 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
10010 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
10020 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
10030 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
10040 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
10050 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
10060 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
10070 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
10080 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
10090 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
100a0 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
100b0 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
100c0 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
100d0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
100e0 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
100f0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
10100 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
10110 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
10120 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
10130 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
10140 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
10150 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
10160 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
10170 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
10180 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
10190 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
101a0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
101b0 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
101c0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
101d0 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
101e0 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
101f0 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
10200 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
10210 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10220 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
10230 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
10240 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
10250 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
10260 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
10270 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
10280 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
10290 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
102a0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
102b0 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
102c0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
102d0 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
102e0 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
102f0 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
10300 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
10310 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
10320 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
10330 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
10340 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
10350 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
10360 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
10370 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
10380 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
10390 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
103a0 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
103b0 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
103c0 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
103d0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
103e0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
103f0 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
10400 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
10410 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
10420 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
10430 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
10440 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
10450 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
10460 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
10470 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
10480 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
10490 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
104a0 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
104b0 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
104c0 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
104d0 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
104e0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
104f0 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
10500 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
10510 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
10520 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
10530 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
10540 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
10550 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
10560 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
10570 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
10580 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
10590 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
105a0 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
105b0 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
105c0 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
105d0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
105e0 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
105f0 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
10600 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
10610 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
10620 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
10630 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
10640 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
10650 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
10660 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
10670 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
10680 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
10690 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
106a0 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
106b0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
106c0 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
106d0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
106e0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
106f0 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
10700 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
10710 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
10720 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
10730 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
10740 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
10750 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
10760 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
10770 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
10780 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
10790 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
107a0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
107b0 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
107c0 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
107d0 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
107e0 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
107f0 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
10800 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
10810 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
10820 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
10830 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
10840 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
10850 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
10860 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
10870 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
10880 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
10890 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
108a0 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
108b0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
108c0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
108d0 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
108e0 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
108f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
10900 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
10910 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
10920 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
10930 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
10940 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
10950 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
10960 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
10970 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
10980 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
10990 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
109a0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
109b0 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
109c0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
109d0 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
109e0 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
109f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10a00 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
10a10 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
10a20 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
10a30 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
10a40 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
10a50 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
10a60 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
10a70 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
10a80 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
10a90 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
10aa0 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
10ab0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10ac0 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
10ad0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
10ae0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
10af0 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
10b00 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
10b10 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
10b20 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
10b30 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
10b40 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
10b50 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
10b60 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
10b70 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e  needs..**.** <b>
10b80 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
10b90 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
10ba0 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
10bb0 2e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  . The applicatio
10bc0 6e 0a 2a 2a 20 6d 75 73 74 20 65 6e 73 75 72 65  n.** must ensure
10bd0 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53   that no other S
10be0 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
10bf0 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20   are invoked by 
10c00 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73  other.** threads
10c10 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63   while sqlite3_c
10c20 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69  onfig() is runni
10c30 6e 67 2e 3c 2f 62 3e 0a 2a 2a 0a 2a 2a 20 54 68  ng.</b>.**.** Th
10c40 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10c50 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  () interface.** 
10c60 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f  may only be invo
10c70 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62  ked prior to lib
10c80 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74  rary initializat
10c90 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ion using.** [sq
10ca0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
10cb0 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75  ()] or after shu
10cc0 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65  tdown by [sqlite
10cd0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a  3_shutdown()]..*
10ce0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  * ^If sqlite3_co
10cf0 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64  nfig() is called
10d00 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
10d10 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e  initialize()] an
10d20 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c  d before.** [sql
10d30 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
10d40 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65   then it will re
10d50 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  turn SQLITE_MISU
10d60 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77  SE..** Note, how
10d70 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69  ever, that ^sqli
10d80 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e  te3_config() can
10d90 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61   be called as pa
10da0 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70  rt of the.** imp
10db0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
10dc0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
10dd0 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f  fined [sqlite3_o
10de0 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  s_init()]..**.**
10df0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
10e00 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
10e10 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e  onfig() is an in
10e20 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67  teger.** [config
10e30 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
10e40 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
10e50 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
10e60 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
10e70 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
10e80 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
10e90 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
10ea0 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
10eb0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10ec0 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
10ed0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
10ee0 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f  **.** ^When a co
10ef0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10f00 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74  on is set, sqlit
10f10 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75  e3_config() retu
10f20 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
10f30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69  .** ^If the opti
10f40 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72  on is unknown or
10f50 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c   SQLite is unabl
10f60 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74  e to set the opt
10f70 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73  ion.** then this
10f80 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
10f90 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72   a non-zero [err
10fa0 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74  or code]..*/.int
10fb0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
10fc0 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a  int, ...);../*.*
10fd0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
10fe0 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63  igure database c
10ff0 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 4d 45  onnections.** ME
11000 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
11010 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
11020 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  db_config() inte
11030 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
11040 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74   make configurat
11050 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ion.** changes t
11060 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  o a [database co
11070 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
11080 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d  interface is sim
11090 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ilar to.** [sqli
110a0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78  te3_config()] ex
110b0 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68  cept that the ch
110c0 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61  anges apply to a
110d0 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61   single.** [data
110e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
110f0 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74   (specified in t
11100 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11110 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  t)..**.** The se
11120 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
11130 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
11140 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20  ig(D,V,...)  is 
11150 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  the.** [SQLITE_D
11160 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
11170 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  E | configuratio
11180 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74  n verb] - an int
11190 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68  eger code .** th
111a0 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61  at indicates wha
111b0 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20  t aspect of the 
111c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
111d0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63  tion] is being c
111e0 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75  onfigured..** Su
111f0 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
11200 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e  ts vary dependin
11210 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  g on the configu
11220 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a  ration verb..**.
11230 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
11240 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11250 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
11260 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  K if and only if
11270 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20  .** the call is 
11280 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65  considered succe
11290 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ssful..*/.int sq
112a0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
112b0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
112c0 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
112d0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
112e0 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
112f0 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
11300 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11310 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
11320 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
11330 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
11340 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
11350 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
11360 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
11370 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
11380 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
11390 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
113a0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
113b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
113c0 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
113d0 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
113e0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
113f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11400 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
11410 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
11420 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
11430 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
11440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
11450 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
11460 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
11470 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
11480 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
11490 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
114a0 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
114b0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
114c0 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
114d0 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
114e0 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
114f0 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
11500 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
11510 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
11520 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
11530 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
11540 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
11550 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
11560 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
11570 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
11580 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
11590 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
115a0 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
115b0 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
115c0 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
115d0 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
115e0 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
115f0 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
11600 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
11610 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
11620 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
11630 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
11640 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
11650 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11660 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
11670 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
11680 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
11690 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
116a0 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
116b0 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
116c0 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
116d0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
116e0 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
116f0 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
11700 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
11710 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
11720 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
11730 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
11740 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
11750 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
11760 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78  * The xMalloc, x
11770 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72  Realloc, and xFr
11780 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ee methods must 
11790 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a  work like the.**
117a0 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
117b0 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
117c0 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74  functions from t
117d0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
117e0 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  brary..** ^SQLit
117f0 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
11800 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
11810 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
11820 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
11830 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
11840 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
11850 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a  to xRoundup..**.
11860 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20  ** xSize should 
11870 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63  return the alloc
11880 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d  ated size of a m
11890 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
118a0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f  .** previously o
118b0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61  btained from xMa
118c0 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63  lloc or xRealloc
118d0 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64  .  The allocated
118e0 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61   size.** is alwa
118f0 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20 62  ys at least as b
11900 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65 73  ig as the reques
11910 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79  ted size but may
11920 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a   be larger..**.*
11930 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d  * The xRoundup m
11940 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68  ethod returns wh
11950 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20  at would be the 
11960 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
11970 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c  f.** a memory al
11980 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61  location given a
11990 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71 75   particular requ
119a0 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73  ested size.  Mos
119b0 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  t memory.** allo
119c0 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
119d0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
119e0 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74  ns at least to t
119f0 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65  he next multiple
11a00 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20  .** of 8.  Some 
11a10 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
11a20 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20   up to a larger 
11a30 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61  multiple or to a
11a40 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20   power of 2..** 
11a50 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  Every memory all
11a60 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
11a70 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67  coming in throug
11a80 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  h [sqlite3_mallo
11a90 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  c()].** or [sqli
11aa0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66  te3_realloc()] f
11ab0 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e  irst calls xRoun
11ac0 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75  dup.  If xRoundu
11ad0 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a  p returns 0, .**
11ae0 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68 65   that causes the
11af0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d   corresponding m
11b00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11b10 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20   to fail..**.** 
11b20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  The xInit method
11b30 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
11b40 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
11b50 72 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  r.  For example,
11b60 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c  .** it might all
11b70 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72  ocate any requir
11b80 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69  e mutexes or ini
11b90 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c  tialize internal
11ba0 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75   data.** structu
11bb0 72 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64  res.  The xShutd
11bc0 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e  own method is in
11bd0 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c  voked (indirectl
11be0 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  y) by.** [sqlite
11bf0 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e  3_shutdown()] an
11c00 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63  d should dealloc
11c10 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65  ate any resource
11c20 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79  s acquired.** by
11c30 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70   xInit.  The pAp
11c40 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73  pData pointer is
11c50 20 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c   used as the onl
11c60 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  y parameter to.*
11c70 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75  * xInit and xShu
11c80 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  tdown..**.** SQL
11c90 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  ite holds the [S
11ca0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
11cb0 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78  IC_MASTER] mutex
11cc0 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73   when it invokes
11cd0 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65  .** the xInit me
11ce0 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e  thod, so the xIn
11cf0 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e  it method need n
11d00 6f 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  ot be threadsafe
11d10 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64  .  The.** xShutd
11d20 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e  own method is on
11d30 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b  ly called from [
11d40 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
11d50 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a  ()] so it does.*
11d60 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  * not need to be
11d70 20 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68   threadsafe eith
11d80 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68  er.  For all oth
11d90 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69  er methods, SQLi
11da0 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20  te.** holds the 
11db0 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
11dc0 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20  ATIC_MEM] mutex 
11dd0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a  as long as the.*
11de0 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
11df0 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66  _MEMSTATUS] conf
11e00 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11e10 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77   is turned on (w
11e20 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79  hich.** it is by
11e30 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f   default) and so
11e40 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65   the methods are
11e50 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73   automatically s
11e60 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f  erialized..** Ho
11e70 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54  wever, if [SQLIT
11e80 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11e90 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c  US] is disabled,
11ea0 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a   then the other.
11eb0 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20  ** methods must 
11ec0 62 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72  be threadsafe or
11ed0 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72   else make their
11ee0 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74   own arrangement
11ef0 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69  s for.** seriali
11f00 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51  zation..**.** SQ
11f10 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
11f20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d  invoke xInit() m
11f30 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69  ore than once wi
11f40 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65  thout an interve
11f50 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20  ning.** call to 
11f60 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a  xShutdown()..*/.
11f70 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
11f80 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11f90 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  ds sqlite3_mem_m
11fa0 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73  ethods;.struct s
11fb0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
11fc0 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ds {.  void *(*x
11fd0 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20  Malloc)(int);   
11fe0 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20        /* Memory 
11ff0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74  allocation funct
12000 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  ion */.  void (*
12010 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20  xFree)(void*);  
12020 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20          /* Free 
12030 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  a prior allocati
12040 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a  on */.  void *(*
12050 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c  xRealloc)(void*,
12060 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65  int);  /* Resize
12070 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
12080 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29  /.  int (*xSize)
12090 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
120a0 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65     /* Return the
120b0 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f   size of an allo
120c0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
120d0 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29  (*xRoundup)(int)
120e0 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f  ;          /* Ro
120f0 75 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73  und up request s
12100 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f  ize to allocatio
12110 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20  n size */.  int 
12120 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b  (*xInit)(void*);
12130 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e             /* In
12140 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
12150 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
12160 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64  .  void (*xShutd
12170 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  own)(void*);    
12180 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a    /* Deinitializ
12190 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  e the memory all
121a0 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64  ocator */.  void
121b0 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
121c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72             /* Ar
121d0 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28  gument to xInit(
121e0 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28  ) and xShutdown(
121f0 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ) */.};../*.** C
12200 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
12210 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a  ration Options.*
12220 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e  * KEYWORDS: {con
12230 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12240 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  n}.**.** These c
12250 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65  onstants are the
12260 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67   available integ
12270 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  er configuration
12280 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a   options that.**
12290 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61   can be passed a
122a0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
122b0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c  ment to the [sql
122c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
122d0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
122e0 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  New configuratio
122f0 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65  n options may be
12300 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
12310 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
12320 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ite..** Existing
12330 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12340 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20  ptions might be 
12350 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41  discontinued.  A
12360 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
12370 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20  hould check the 
12380 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d  return code from
12390 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
123a0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
123b0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
123c0 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b  l worked.  The [
123d0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
123e0 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
123f0 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
12400 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
12410 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
12420 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
12430 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
12440 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
12450 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
12460 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  l>.** [[SQLITE_C
12470 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
12480 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
12490 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
124a0 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
124b0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
124c0 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
124d0 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
124e0 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
124f0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
12500 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65  ] to Single-thre
12510 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
12520 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
12530 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67  .** all mutexing
12540 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65   and puts SQLite
12550 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65   into a mode whe
12560 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62  re it can only b
12570 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73  e used.** by a s
12580 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20  ingle thread.   
12590 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
125a0 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
125b0 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
125c0 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
125d0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
125e0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
125f0 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
12600 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63  ot possible to c
12610 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61  hange the [threa
12620 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20  ding mode] from 
12630 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76  its default.** v
12640 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74  alue of Single-t
12650 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71  hread and so [sq
12660 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12670 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20  will return .** 
12680 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
12690 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
126a0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
126b0 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20  SINGLETHREAD.** 
126c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
126d0 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
126e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
126f0 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c  _MULTITHREAD]] <
12700 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12710 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74  _MULTITHREAD</dt
12720 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61  >.** <dd>There a
12730 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  re no arguments 
12740 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20  to this option. 
12750 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65   ^This option se
12760 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61  ts the.** [threa
12770 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75  ding mode] to Mu
12780 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  lti-thread.  In 
12790 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
127a0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65  disables.** mute
127b0 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73  xing on [databas
127c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
127d0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
127e0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
127f0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
12800 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  on is responsibl
12810 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e  e for serializin
12820 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b  g access to.** [
12830 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12840 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
12850 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e  red statements].
12860 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65    But other mute
12870 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c  xes.** are enabl
12880 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74  ed so that SQLit
12890 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74  e will be safe t
128a0 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69  o use in a multi
128b0 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76  -threaded.** env
128c0 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67  ironment as long
128d0 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61   as no two threa
128e0 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73  ds attempt to us
128f0 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64  e the same.** [d
12900 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12910 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20  on] at the same 
12920 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74  time.  ^If SQLit
12930 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12940 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
12950 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
12960 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12970 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
12980 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
12990 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
129a0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75  le to set the Mu
129b0 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
129c0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a  ading mode] and.
129d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
129e0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
129f0 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
12a00 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
12a10 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f  the.** SQLITE_CO
12a20 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
12a30 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12a40 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
12a50 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12a60 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c  G_SERIALIZED]] <
12a70 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12a80 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
12a90 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
12aa0 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
12ab0 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
12ac0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
12ad0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
12ae0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
12af0 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
12b00 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
12b10 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
12b20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
12b30 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
12b40 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
12b50 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
12b60 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
12b70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
12b80 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
12b90 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
12ba0 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
12bb0 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
12bc0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
12bd0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12be0 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
12bf0 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
12c00 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
12c10 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
12c20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12c30 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
12c40 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
12c50 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
12c60 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
12c70 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
12c80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
12c90 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
12ca0 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
12cb0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
12cc0 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
12cd0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
12ce0 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
12cf0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12d00 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
12d10 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
12d20 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
12d30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
12d40 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
12d50 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
12d60 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
12d70 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
12d80 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
12d90 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12da0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
12db0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
12dc0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
12dd0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
12de0 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
12df0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
12e00 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12e10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
12e20 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
12e30 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f  _CONFIG_MALLOC</
12e40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12e50 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12e60 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20 74 61  MALLOC option ta
12e70 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
12e80 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 0a  ument which is .
12e90 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** a pointer to 
12ea0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
12eb0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12ec0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12ed0 72 65 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d  re..** The argum
12ee0 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
12ef0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
12f00 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
12f10 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12f20 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
12f30 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
12f40 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12f50 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
12f60 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
12f70 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
12f80 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
12f90 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
12fa0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
12fb0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
12fc0 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
12fd0 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
12fe0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
12ff0 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
13000 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13010 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
13020 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13030 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
13040 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 65  t>.** <dd> ^(The
13050 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
13060 45 54 4d 41 4c 4c 4f 43 20 6f 70 74 69 6f 6e 20  ETMALLOC option 
13070 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13080 72 67 75 6d 65 6e 74 20 77 68 69 63 68 0a 2a 2a  rgument which.**
13090 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
130a0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
130b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
130c0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
130d0 75 72 65 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  ure..** The [sql
130e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
130f0 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69  ].** structure i
13100 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68  s filled with th
13110 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69  e currently defi
13120 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ned memory alloc
13130 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29  ation routines.)
13140 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e  ^.** This option
13150 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
13160 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66  overload the def
13170 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ault memory allo
13180 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
13190 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
131a0 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f  r that simulatio
131b0 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ns memory alloca
131c0 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a  tion failure or.
131d0 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79  ** tracks memory
131e0 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d   usage, for exam
131f0 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ple. </dd>.**.**
13200 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13210 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74  _MEMSTATUS]] <dt
13220 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13230 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a  EMSTATUS</dt>.**
13240 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
13250 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
13260 55 53 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  US option takes 
13270 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
13280 6f 66 20 74 79 70 65 20 69 6e 74 2c 0a 2a 2a 20  of type int,.** 
13290 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
132a0 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
132b0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
132c0 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
132d0 6f 6e 20 6f 66 0a 2a 2a 20 6d 65 6d 6f 72 79 20  on of.** memory 
132e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
132f0 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
13300 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13310 73 74 61 74 69 73 74 69 63 73 20 61 72 65 0a 2a  statistics are.*
13320 2a 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  * disabled, the 
13330 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65  following SQLite
13340 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f   interfaces beco
13350 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e  me non-operation
13360 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a  al:.**   <ul>.**
13370 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
13380 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a  _memory_used()].
13390 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
133a0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
133b0 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  ter()].**   <li>
133c0 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68   [sqlite3_soft_h
133d0 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a  eap_limit64()].*
133e0 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
133f0 33 5f 73 74 61 74 75 73 36 34 28 29 5d 0a 2a 2a  3_status64()].**
13400 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
13410 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13420 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
13430 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
13440 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
13450 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
13460 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
13470 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
13480 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
13490 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
134a0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
134b0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
134c0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
134d0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
134e0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
134f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13500 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
13510 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
13520 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
13530 54 43 48 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  TCH option speci
13540 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
13550 6d 6f 72 79 20 62 75 66 66 65 72 0a 2a 2a 20 74  mory buffer.** t
13560 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
13570 73 65 20 66 6f 72 20 73 63 72 61 74 63 68 20 6d  se for scratch m
13580 65 6d 6f 72 79 2e 20 20 5e 28 54 68 65 72 65 20  emory.  ^(There 
13590 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
135a0 6e 74 73 0a 2a 2a 20 74 6f 20 53 51 4c 49 54 45  nts.** to SQLITE
135b0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3a  _CONFIG_SCRATCH:
135c0 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38    A pointer an 8
135d0 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64  -byte.** aligned
135e0 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66   memory buffer f
135f0 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63  rom which the sc
13600 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
13610 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61  s will be.** dra
13620 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20  wn, the size of 
13630 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c  each scratch all
13640 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a  ocation (sz),.**
13650 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
13660 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74   number of scrat
13670 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28  ch allocations (
13680 4e 29 2e 29 5e 0a 2a 2a 20 54 68 65 20 66 69 72  N).)^.** The fir
13690 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
136a0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
136b0 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
136c0 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
136d0 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
136e0 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
136f0 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  * ^SQLite will n
13700 6f 74 20 75 73 65 20 6d 6f 72 65 20 74 68 61 6e  ot use more than
13710 20 6f 6e 65 20 73 63 72 61 74 63 68 20 62 75 66   one scratch buf
13720 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e  fers per thread.
13730 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
13740 20 6e 65 76 65 72 20 72 65 71 75 65 73 74 20 61   never request a
13750 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
13760 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
13770 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
13780 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
13790 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69  ize..** ^If SQLi
137a0 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61  te needs needs a
137b0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72  dditional.** scr
137c0 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f  atch memory beyo
137d0 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
137e0 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66  ded by this conf
137f0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13800 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69  , then .** [sqli
13810 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69  te3_malloc()] wi
13820 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  ll be used to ob
13830 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  tain the memory 
13840 6e 65 65 64 65 64 2e 3c 70 3e 0a 2a 2a 20 5e 57  needed.<p>.** ^W
13850 68 65 6e 20 74 68 65 20 61 70 70 6c 69 63 61 74  hen the applicat
13860 69 6f 6e 20 70 72 6f 76 69 64 65 73 20 61 6e 79  ion provides any
13870 20 61 6d 6f 75 6e 74 20 6f 66 20 73 63 72 61 74   amount of scrat
13880 63 68 20 6d 65 6d 6f 72 79 20 75 73 69 6e 67 0a  ch memory using.
13890 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
138a0 5f 53 43 52 41 54 43 48 2c 20 53 51 4c 69 74 65  _SCRATCH, SQLite
138b0 20 61 76 6f 69 64 73 20 75 6e 6e 65 63 65 73 73   avoids unnecess
138c0 61 72 79 20 6c 61 72 67 65 0a 2a 2a 20 5b 73 71  ary large.** [sq
138d0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 7c 68 65 61  lite3_malloc|hea
138e0 70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 5d 2e 0a  p allocations]..
138f0 2a 2a 20 54 68 69 73 20 63 61 6e 20 68 65 6c 70  ** This can help
13900 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 7c 70   [Robson proof|p
13910 72 65 76 65 6e 74 20 6d 65 6d 6f 72 79 20 61 6c  revent memory al
13920 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65  location failure
13930 73 5d 20 64 75 65 20 74 6f 20 68 65 61 70 0a 2a  s] due to heap.*
13940 2a 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20  * fragmentation 
13950 69 6e 20 6c 6f 77 2d 6d 65 6d 6f 72 79 20 65 6d  in low-memory em
13960 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 0a  bedded systems..
13970 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
13980 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13990 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
139a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
139b0 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
139c0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
139d0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
139e0 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
139f0 73 20 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a  s a memory pool.
13a00 2a 2a 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  ** that SQLite c
13a10 61 6e 20 75 73 65 20 66 6f 72 20 74 68 65 20 64  an use for the d
13a20 61 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63  atabase page cac
13a30 68 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61  he with the defa
13a40 75 6c 74 20 70 61 67 65 0a 2a 2a 20 63 61 63 68  ult page.** cach
13a50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
13a60 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
13a70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13a80 20 69 73 20 61 20 6e 6f 2d 6f 70 20 69 66 20 61   is a no-op if a
13a90 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
13aa0 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
13ab0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
13ac0 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
13ad0 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
13ae0 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 2e 0a 2a  NFIG_PCACHE2]..*
13af0 2a 20 5e 54 68 65 72 65 20 61 72 65 20 74 68 72  * ^There are thr
13b00 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  ee arguments to 
13b10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
13b20 47 45 43 41 43 48 45 3a 20 41 20 70 6f 69 6e 74  GECACHE: A point
13b30 65 72 20 74 6f 0a 2a 2a 20 38 2d 62 79 74 65 20  er to.** 8-byte 
13b40 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 28  aligned memory (
13b50 70 4d 65 6d 29 2c 20 74 68 65 20 73 69 7a 65 20  pMem), the size 
13b60 6f 66 20 65 61 63 68 20 70 61 67 65 20 63 61 63  of each page cac
13b70 68 65 20 6c 69 6e 65 20 28 73 7a 29 2c 0a 2a 2a  he line (sz),.**
13b80 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
13b90 6f 66 20 63 61 63 68 65 20 6c 69 6e 65 73 20 28  of cache lines (
13ba0 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72  N)..** The sz ar
13bb0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
13bc0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
13bd0 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61 73   largest databas
13be0 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77  e page.** (a pow
13bf0 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65  er of two betwee
13c00 6e 20 35 31 32 20 61 6e 64 20 36 35 35 33 36 29  n 512 and 65536)
13c10 20 70 6c 75 73 20 73 6f 6d 65 20 65 78 74 72 61   plus some extra
13c20 20 62 79 74 65 73 20 66 6f 72 20 65 61 63 68 0a   bytes for each.
13c30 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20  ** page header. 
13c40 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
13c50 65 78 74 72 61 20 62 79 74 65 73 20 6e 65 65 64  extra bytes need
13c60 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 68  ed by the page h
13c70 65 61 64 65 72 0a 2a 2a 20 63 61 6e 20 62 65 20  eader.** can be 
13c80 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
13c90 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13ca0 50 43 41 43 48 45 5f 48 44 52 53 5a 5d 2e 0a 2a  PCACHE_HDRSZ]..*
13cb0 2a 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73  * ^It is harmles
13cc0 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68  s, apart from th
13cd0 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c  e wasted memory,
13ce0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 7a 20 70  .** for the sz p
13cf0 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 6c  arameter to be l
13d00 61 72 67 65 72 20 74 68 61 6e 20 6e 65 63 65 73  arger than neces
13d10 73 61 72 79 2e 20 20 54 68 65 20 70 4d 65 6d 0a  sary.  The pMem.
13d20 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
13d30 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c   be either a NUL
13d40 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 20 70  L pointer or a p
13d50 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
13d60 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 62  yte.** aligned b
13d70 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 6f  lock of memory o
13d80 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
13d90 62 79 74 65 73 2c 20 6f 74 68 65 72 77 69 73 65  bytes, otherwise
13da0 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 62  .** subsequent b
13db0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
13dc0 69 6e 65 64 2e 0a 2a 2a 20 5e 57 68 65 6e 20 70  ined..** ^When p
13dd0 4d 65 6d 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  Mem is not NULL,
13de0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 73 74 72   SQLite will str
13df0 69 76 65 20 74 6f 20 75 73 65 20 74 68 65 20 6d  ive to use the m
13e00 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 0a 2a  emory provided.*
13e10 2a 20 74 6f 20 73 61 74 69 73 66 79 20 70 61 67  * to satisfy pag
13e20 65 20 63 61 63 68 65 20 6e 65 65 64 73 2c 20 66  e cache needs, f
13e30 61 6c 6c 69 6e 67 20 62 61 63 6b 20 74 6f 20 5b  alling back to [
13e40 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
13e50 5d 20 69 66 0a 2a 2a 20 61 20 70 61 67 65 20 63  ] if.** a page c
13e60 61 63 68 65 20 6c 69 6e 65 20 69 73 20 6c 61 72  ache line is lar
13e70 67 65 72 20 74 68 61 6e 20 73 7a 20 62 79 74 65  ger than sz byte
13e80 73 20 6f 72 20 69 66 20 61 6c 6c 20 6f 66 20 74  s or if all of t
13e90 68 65 20 70 4d 65 6d 20 62 75 66 66 65 72 0a 2a  he pMem buffer.*
13ea0 2a 20 69 73 20 65 78 68 61 75 73 74 65 64 2e 0a  * is exhausted..
13eb0 2a 2a 20 5e 49 66 20 70 4d 65 6d 20 69 73 20 4e  ** ^If pMem is N
13ec0 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 6e 6f 6e  ULL and N is non
13ed0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 65 61 63 68  -zero, then each
13ee0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
13ef0 74 69 6f 6e 0a 2a 2a 20 64 6f 65 73 20 61 6e 20  tion.** does an 
13f00 69 6e 69 74 69 61 6c 20 62 75 6c 6b 20 61 6c 6c  initial bulk all
13f10 6f 63 61 74 69 6f 6e 20 66 6f 72 20 70 61 67 65  ocation for page
13f20 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a   cache memory.**
13f30 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
13f40 61 6c 6c 6f 63 28 29 5d 20 73 75 66 66 69 63 69  alloc()] suffici
13f50 65 6e 74 20 66 6f 72 20 4e 20 63 61 63 68 65 20  ent for N cache 
13f60 6c 69 6e 65 73 20 69 66 20 4e 20 69 73 20 70 6f  lines if N is po
13f70 73 69 74 69 76 65 20 6f 72 0a 2a 2a 20 6f 66 20  sitive or.** of 
13f80 2d 31 30 32 34 2a 4e 20 62 79 74 65 73 20 69 66  -1024*N bytes if
13f90 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20   N is negative, 
13fa0 2e 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c  . ^If additional
13fb0 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d  .** page cache m
13fc0 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20  emory is needed 
13fd0 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
13fe0 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 69  rovided by the i
13ff0 6e 69 74 69 61 6c 0a 2a 2a 20 61 6c 6c 6f 63 61  nitial.** alloca
14000 74 69 6f 6e 2c 20 74 68 65 6e 20 53 51 4c 69 74  tion, then SQLit
14010 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74  e goes to [sqlit
14020 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 73 65 70  e3_malloc()] sep
14030 61 72 61 74 65 6c 79 20 66 6f 72 20 65 61 63 68  arately for each
14040 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  .** additional c
14050 61 63 68 65 20 6c 69 6e 65 2e 20 3c 2f 64 64 3e  ache line. </dd>
14060 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14070 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64  CONFIG_HEAP]] <d
14080 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14090 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  HEAP</dt>.** <dd
140a0 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  > ^The SQLITE_CO
140b0 4e 46 49 47 5f 48 45 41 50 20 6f 70 74 69 6f 6e  NFIG_HEAP option
140c0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
140d0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
140e0 72 20 0a 2a 2a 20 74 68 61 74 20 53 51 4c 69 74  r .** that SQLit
140f0 65 20 77 69 6c 6c 20 75 73 65 20 66 6f 72 20 61  e will use for a
14100 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
14110 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
14120 69 6f 6e 20 6e 65 65 64 73 0a 2a 2a 20 62 65 79  ion needs.** bey
14130 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
14140 65 64 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ed for by [SQLIT
14150 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
14160 5d 20 61 6e 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  ] and.** [SQLITE
14170 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
14180 45 5d 2e 0a 2a 2a 20 5e 54 68 65 20 53 51 4c 49  E]..** ^The SQLI
14190 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 6f  TE_CONFIG_HEAP o
141a0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
141b0 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
141c0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a  e is compiled.**
141d0 20 77 69 74 68 20 65 69 74 68 65 72 20 5b 53 51   with either [SQ
141e0 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
141f0 59 53 33 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  YS3] or [SQLITE_
14200 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20  ENABLE_MEMSYS5] 
14210 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  and returns.** [
14220 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
14230 20 69 6e 76 6f 6b 65 64 20 6f 74 68 65 72 77 69   invoked otherwi
14240 73 65 2e 0a 2a 2a 20 5e 54 68 65 72 65 20 61 72  se..** ^There ar
14250 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
14260 73 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46  s to SQLITE_CONF
14270 49 47 5f 48 45 41 50 3a 0a 2a 2a 20 41 6e 20 38  IG_HEAP:.** An 8
14280 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f  -byte aligned po
14290 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d  inter to the mem
142a0 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  ory,.** the numb
142b0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
142c0 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  he memory buffer
142d0 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75  , and the minimu
142e0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
142f0 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  e..** ^If the fi
14300 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
14310 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
14320 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53   is NULL, then S
14330 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a  QLite reverts.**
14340 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65   to using its de
14350 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  fault memory all
14360 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73 74  ocator (the syst
14370 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c  em malloc() impl
14380 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20  ementation),.** 
14390 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f  undoing any prio
143a0 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  r invocation of 
143b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
143c0 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65  ALLOC].  ^If the
143d0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  .** memory point
143e0 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  er is not NULL t
143f0 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
14400 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
14410 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
14420 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
14430 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
14440 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
14450 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
14460 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
14470 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
14480 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
14490 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
144a0 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
144b0 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
144c0 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
144d0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
144e0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
144f0 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
14500 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
14510 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
14520 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
14530 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
14540 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
14550 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
14560 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14570 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
14580 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14590 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
145a0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
145b0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 6f 70 74  CONFIG_MUTEX opt
145c0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
145d0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
145e0 68 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  h is a.** pointe
145f0 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
14600 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
14610 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
14620 73 74 72 75 63 74 75 72 65 2e 0a 2a 2a 20 54 68  structure..** Th
14630 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
14640 66 69 65 73 20 61 6c 74 65 72 6e 61 74 69 76 65  fies alternative
14650 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
14660 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
14670 75 73 65 64 0a 2a 2a 20 69 6e 20 70 6c 61 63 65  used.** in place
14680 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
14690 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
146a0 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
146b0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
146c0 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
146d0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
146e0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
146f0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
14700 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
14710 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
14720 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
14730 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
14740 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
14750 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14760 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
14770 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
14780 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
14790 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
147a0 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
147b0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
147c0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
147d0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
147e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
147f0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
14800 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
14810 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
14820 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
14830 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
14840 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
14850 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
14860 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
14870 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
14880 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
14890 3c 64 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54  <dd> ^(The SQLIT
148a0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
148b0 58 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  X option takes a
148c0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
148d0 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70   which.** is a p
148e0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
148f0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
14900 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
14910 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
14920 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
14930 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a  _mutex_methods].
14940 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
14950 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
14960 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
14970 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  d mutex routines
14980 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
14990 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
149a0 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
149b0 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
149c0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
149d0 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
149e0 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
149f0 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
14a00 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
14a10 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
14a20 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
14a30 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  e.   ^If SQLite 
14a40 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
14a50 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
14a60 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
14a70 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
14a80 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
14a90 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
14aa0 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
14ab0 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
14ac0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
14ad0 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
14ae0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
14af0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
14b00 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
14b10 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63  ONFIG_GETMUTEX c
14b20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14b30 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
14b40 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
14b50 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
14b60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
14b70 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51  OKASIDE]] <dt>SQ
14b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14b90 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
14ba0 64 3e 20 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  d> ^(The SQLITE_
14bb0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
14bc0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
14bd0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
14be0 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 74 68   determine.** th
14bf0 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65 20 6f  e default size o
14c00 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  f lookaside memo
14c10 72 79 20 6f 6e 20 65 61 63 68 20 5b 64 61 74 61  ry on each [data
14c20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
14c30 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
14c40 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
14c50 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
14c60 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
14c70 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
14c80 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
14c90 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
14ca0 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
14cb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14cc0 69 6f 6e 2e 29 5e 20 20 5e 28 53 51 4c 49 54 45  ion.)^  ^(SQLITE
14cd0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
14ce0 45 0a 2a 2a 20 73 65 74 73 20 74 68 65 20 3c 69  E.** sets the <i
14cf0 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f  >default</i> loo
14d00 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65  kaside size. The
14d10 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
14d20 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20  G_LOOKASIDE].** 
14d30 6f 70 74 69 6f 6e 20 74 6f 20 5b 73 71 6c 69 74  option to [sqlit
14d40 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
14d50 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
14d60 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
14d70 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
14d80 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
14d90 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
14da0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
14db0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
14dc0 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
14dd0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
14de0 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
14df0 28 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  (The SQLITE_CONF
14e00 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f  IG_PCACHE2 optio
14e10 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
14e20 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
14e30 69 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  is .** a pointer
14e40 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
14e50 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14e60 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f   object.  This o
14e70 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 0a  bject specifies.
14e80 2a 2a 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  ** the interface
14e90 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67   to a custom pag
14ea0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
14eb0 74 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 53 51  tation.)^.** ^SQ
14ec0 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
14ed0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
14ee0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14ef0 32 5d 20 6f 62 6a 65 63 74 2e 3c 2f 64 64 3e 0a  2] object.</dd>.
14f00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14f10 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
14f20 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
14f30 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
14f40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
14f50 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
14f60 5f 47 45 54 50 43 41 43 48 45 32 20 6f 70 74 69  _GETPCACHE2 opti
14f70 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
14f80 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
14f90 0a 2a 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72  .** is a pointer
14fa0 20 74 6f 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   to an [sqlite3_
14fb0 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
14fc0 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
14fd0 20 63 6f 70 69 65 73 20 6f 66 0a 2a 2a 20 74 68   copies of.** th
14fe0 65 20 63 75 72 72 65 6e 74 20 70 61 67 65 20 63  e current page c
14ff0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
15000 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
15010 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
15020 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15030 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
15040 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
15050 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65  /dt>.** <dd> The
15060 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
15070 4f 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  OG option is use
15080 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74  d to configure t
15090 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f  he SQLite.** glo
150a0 62 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e  bal [error log].
150b0 0a 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45  .** (^The SQLITE
150c0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69  _CONFIG_LOG opti
150d0 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67  on takes two arg
150e0 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65  uments: a pointe
150f0 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69  r to a.** functi
15100 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73  on with a call s
15110 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64  ignature of void
15120 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  (*)(void*,int,co
15130 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20  nst char*), .** 
15140 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  and a pointer to
15150 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66   void. ^If the f
15160 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
15170 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20  is not NULL, it 
15180 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79  is.** invoked by
15190 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
151a0 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68   to process each
151b0 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20   logging event. 
151c0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63   ^If the.** func
151d0 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
151e0 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74  NULL, the [sqlit
151f0 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66  e3_log()] interf
15200 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f  ace becomes a no
15210 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69  -op..** ^The voi
15220 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  d pointer that i
15230 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  s the second arg
15240 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f  ument to SQLITE_
15250 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a  CONFIG_LOG is.**
15260 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
15270 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  as the first par
15280 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70  ameter to the ap
15290 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
152a0 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63  d logger.** func
152b0 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68  tion whenever th
152c0 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69  at function is i
152d0 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65  nvoked.  ^The se
152e0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
152f0 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20  o.** the logger 
15300 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f  function is a co
15310 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  py of the first 
15320 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
15330 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
15340 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  * [sqlite3_log()
15350 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e  ] call and is in
15360 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b  tended to be a [
15370 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20  result code] or 
15380 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  an.** [extended 
15390 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e  result code].  ^
153a0 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
153b0 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68  ter passed to th
153c0 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c  e logger is.** l
153d0 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72  og message after
153e0 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20   formatting via 
153f0 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
15400 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  f()]..** The SQL
15410 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65  ite logging inte
15420 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65  rface is not ree
15430 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67  ntrant; the logg
15440 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73  er function.** s
15450 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61  upplied by the a
15460 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
15470 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53  not invoke any S
15480 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
15490 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74  .** In a multi-t
154a0 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74  hreaded applicat
154b0 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61  ion, the applica
154c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
154d0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
154e0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
154f0 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  fe. </dd>.**.** 
15500 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15510 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  URI]] <dt>SQLITE
15520 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c  _CONFIG_URI.** <
15530 64 64 3e 5e 28 54 68 65 20 53 51 4c 49 54 45 5f  dd>^(The SQLITE_
15540 43 4f 4e 46 49 47 5f 55 52 49 20 6f 70 74 69 6f  CONFIG_URI optio
15550 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15560 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70   argument of typ
15570 65 20 69 6e 74 2e 0a 2a 2a 20 49 66 20 6e 6f 6e  e int..** If non
15580 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20  -zero, then URI 
15590 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
155a0 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66  ally enabled. If
155b0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
155c0 73 20 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20  s zero,.** then 
155d0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
155e0 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
155f0 64 2e 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e  d.)^ ^If URI han
15600 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
15610 79 0a 2a 2a 20 65 6e 61 62 6c 65 64 2c 20 61 6c  y.** enabled, al
15620 6c 20 66 69 6c 65 6e 61 6d 65 73 20 70 61 73 73  l filenames pass
15630 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ed to [sqlite3_o
15640 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
15650 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 0a 2a 2a 20  _open_v2()],.** 
15660 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
15670 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
15680 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
15690 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
156a0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
156b0 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
156c0 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
156d0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
156e0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
156f0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
15700 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
15710 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
15720 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69 73 20  ened. ^If it is 
15730 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65  globally disable
15740 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65  d, filenames are
15750 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72  .** only interpr
15760 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20  eted as URIs if 
15770 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  the SQLITE_OPEN_
15780 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20  URI flag is set 
15790 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61  when the.** data
157a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
157b0 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42 79 20  is opened. ^(By 
157c0 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
157d0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
157e0 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
157f0 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
15800 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
15810 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
15820 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
15830 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
15840 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a   defined.)^.**.*
15850 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15860 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
15870 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49  _SCAN]] <dt>SQLI
15880 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49  TE_CONFIG_COVERI
15890 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a  NG_INDEX_SCAN.**
158a0 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49 54 45   <dd>^The SQLITE
158b0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
158c0 5f 49 4e 44 45 58 5f 53 43 41 4e 20 6f 70 74 69  _INDEX_SCAN opti
158d0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
158e0 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 61 72 67  e integer.** arg
158f0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
15900 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
15910 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
15920 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
15930 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 75 73 65  sable.** the use
15940 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
15950 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
15960 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
15970 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
15980 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
15990 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
159a0 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
159b0 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
159c0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
159d0 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
159e0 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
159f0 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
15a00 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
15a10 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
15a20 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
15a30 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
15a40 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
15a50 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
15a60 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
15a70 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
15a80 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
15a90 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
15aa0 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
15ab0 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68  ction.** when th
15ac0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
15ad0 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
15ae0 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
15af0 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
15b00 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
15b10 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
15b20 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
15b30 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
15b40 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
15b50 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
15b60 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
15b70 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
15b80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
15b90 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
15ba0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
15bb0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
15bc0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
15bd0 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
15be0 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
15bf0 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
15c00 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
15c10 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
15c20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
15c30 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
15c40 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
15c50 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
15c60 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
15c70 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a  o-ops..** </dd>.
15c80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
15c90 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a  ONFIG_SQLLOG]].*
15ca0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
15cb0 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64  FIG_SQLLOG.** <d
15cc0 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  d>This option is
15cd0 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
15ce0 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d  if sqlite is com
15cf0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
15d00 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
15d10 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f  _SQLLOG] pre-pro
15d20 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66  cessor macro def
15d30 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20  ined. The first 
15d40 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a  argument should.
15d50 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ** be a pointer 
15d60 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66  to a function of
15d70 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f   type void(*)(vo
15d80 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e  id*,sqlite3*,con
15d90 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a  st char*, int)..
15da0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68  ** The second sh
15db0 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20  ould be of type 
15dc0 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c  (void*). The cal
15dd0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
15de0 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a   by the library.
15df0 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61  ** in three sepa
15e00 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63  rate circumstanc
15e10 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62  es, identified b
15e20 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73  y the value pass
15e30 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75  ed as the.** fou
15e40 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49  rth parameter. I
15e50 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
15e60 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65  ameter is 0, the
15e70 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
15e80 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73  onnection.** pas
15e90 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
15ea0 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a  d argument has j
15eb0 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e  ust been opened.
15ec0 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
15ed0 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ent.** points to
15ee0 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69   a buffer contai
15ef0 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66  ning the name of
15f00 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61   the main databa
15f10 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a  se file. If the.
15f20 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  ** fourth parame
15f30 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74  ter is 1, then t
15f40 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
15f50 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20   that the third 
15f60 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69  parameter.** poi
15f70 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20  nts to has just 
15f80 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f  been executed. O
15f90 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68  r, if the fourth
15fa0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c   parameter is 2,
15fb0 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e   then.** the con
15fc0 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61  nection being pa
15fd0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
15fe0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
15ff0 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68  being closed. Th
16000 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d  e.** third param
16010 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e  eter is passed N
16020 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65  ULL In this case
16030 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66  .  An example of
16040 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63   using this.** c
16050 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
16060 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20  ion can be seen 
16070 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c  in the "test_sql
16080 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69  log.c" source fi
16090 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e  le in.** the can
160a0 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f  onical SQLite so
160b0 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a  urce tree.</dd>.
160c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
160d0 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d  ONFIG_MMAP_SIZE]
160e0 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
160f0 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
16100 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f  .** <dd>^SQLITE_
16110 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
16120 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69   takes two 64-bi
16130 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74  t integer (sqlit
16140 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73  e3_int64) values
16150 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65  .** that are the
16160 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69   default mmap si
16170 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65  ze limit (the de
16180 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f  fault setting fo
16190 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61  r.** [PRAGMA mma
161a0 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65  p_size]) and the
161b0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
161c0 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
161d0 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
161e0 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65  t setting can be
161f0 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65   overridden by e
16200 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ach database con
16210 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  nection using.**
16220 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41   either the [PRA
16230 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63  GMA mmap_size] c
16240 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73  ommand, or by us
16250 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ing the.** [SQLI
16260 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
16270 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  ZE] file control
16280 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d  .  ^(The maximum
16290 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
162a0 7a 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 69  ze.** will be si
162b0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
162c0 20 69 66 20 6e 65 63 65 73 73 61 72 79 20 73 6f   if necessary so
162d0 20 74 68 61 74 20 69 74 20 64 6f 65 73 20 6e 6f   that it does no
162e0 74 20 65 78 63 65 65 64 20 74 68 65 0a 2a 2a 20  t exceed the.** 
162f0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78  compile-time max
16300 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73  imum mmap size s
16310 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51  et by the.** [SQ
16320 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49  LITE_MAX_MMAP_SI
16330 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  ZE] compile-time
16340 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49   option.)^.** ^I
16350 66 20 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e  f either argumen
16360 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  t to this option
16370 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
16380 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74  en that argument
16390 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74   is.** changed t
163a0 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69  o its compile-ti
163b0 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  me default..**.*
163c0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
163d0 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
163e0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
163f0 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
16400 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54  APSIZE.** <dd>^T
16410 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16420 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
16430 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
16440 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69  vailable if SQLi
16450 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
16460 64 20 66 6f 72 20 57 69 6e 64 6f 77 73 20 77 69  d for Windows wi
16470 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57  th the [SQLITE_W
16480 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65  IN32_MALLOC] pre
16490 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
164a0 0a 2a 2a 20 64 65 66 69 6e 65 64 2e 20 5e 53 51  .** defined. ^SQ
164b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33  LITE_CONFIG_WIN3
164c0 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73  2_HEAPSIZE takes
164d0 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e   a 32-bit unsign
164e0 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  ed integer value
164f0 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66 69  .** that specifi
16500 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73  es the maximum s
16510 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61 74  ize of the creat
16520 65 64 20 68 65 61 70 2e 0a 2a 2a 0a 2a 2a 20 5b  ed heap..**.** [
16530 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
16540 43 41 43 48 45 5f 48 44 52 53 5a 5d 5d 0a 2a 2a  CACHE_HDRSZ]].**
16550 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16560 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 0a  IG_PCACHE_HDRSZ.
16570 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
16580 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16590 5f 48 44 52 53 5a 20 6f 70 74 69 6f 6e 20 74 61  _HDRSZ option ta
165a0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 70 61 72  kes a single par
165b0 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ameter which.** 
165c0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
165d0 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64 20 77  an integer and w
165e0 72 69 74 65 73 20 69 6e 74 6f 20 74 68 61 74 20  rites into that 
165f0 69 6e 74 65 67 65 72 20 74 68 65 20 6e 75 6d 62  integer the numb
16600 65 72 20 6f 66 20 65 78 74 72 61 0a 2a 2a 20 62  er of extra.** b
16610 79 74 65 73 20 70 65 72 20 70 61 67 65 20 72 65  ytes per page re
16620 71 75 69 72 65 64 20 66 6f 72 20 65 61 63 68 20  quired for each 
16630 70 61 67 65 20 69 6e 20 5b 53 51 4c 49 54 45 5f  page in [SQLITE_
16640 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
16650 5d 2e 0a 2a 2a 20 54 68 65 20 61 6d 6f 75 6e 74  ]..** The amount
16660 20 6f 66 20 65 78 74 72 61 20 73 70 61 63 65 20   of extra space 
16670 72 65 71 75 69 72 65 64 20 63 61 6e 20 63 68 61  required can cha
16680 6e 67 65 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  nge depending on
16690 20 74 68 65 20 63 6f 6d 70 69 6c 65 72 2c 0a 2a   the compiler,.*
166a0 2a 20 74 61 72 67 65 74 20 70 6c 61 74 66 6f 72  * target platfor
166b0 6d 2c 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65  m, and SQLite ve
166c0 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  rsion..**.** [[S
166d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41  QLITE_CONFIG_PMA
166e0 53 5a 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  SZ]].** <dt>SQLI
166f0 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 0a  TE_CONFIG_PMASZ.
16700 2a 2a 20 3c 64 64 3e 5e 54 68 65 20 53 51 4c 49  ** <dd>^The SQLI
16710 54 45 5f 43 4f 4e 46 49 47 5f 50 4d 41 53 5a 20  TE_CONFIG_PMASZ 
16720 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
16730 69 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20  ingle parameter 
16740 77 68 69 63 68 0a 2a 2a 20 69 73 20 61 6e 20 75  which.** is an u
16750 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
16760 61 6e 64 20 73 65 74 73 20 74 68 65 20 22 4d 69  and sets the "Mi
16770 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 22 20  nimum PMA Size" 
16780 66 6f 72 20 74 68 65 20 6d 75 6c 74 69 74 68 72  for the multithr
16790 65 61 64 65 64 0a 2a 2a 20 73 6f 72 74 65 72 20  eaded.** sorter 
167a0 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65 72 2e  to that integer.
167b0 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 6d 69    The default mi
167c0 6e 69 6d 75 6d 20 50 4d 41 20 53 69 7a 65 20 69  nimum PMA Size i
167d0 73 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20  s set by the.** 
167e0 5b 53 51 4c 49 54 45 5f 53 4f 52 54 45 52 5f 50  [SQLITE_SORTER_P
167f0 4d 41 53 5a 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  MASZ] compile-ti
16800 6d 65 20 6f 70 74 69 6f 6e 2e 20 20 4e 65 77 20  me option.  New 
16810 74 68 72 65 61 64 73 20 61 72 65 20 6c 61 75 6e  threads are laun
16820 63 68 65 64 0a 2a 2a 20 74 6f 20 68 65 6c 70 20  ched.** to help 
16830 77 69 74 68 20 73 6f 72 74 20 6f 70 65 72 61 74  with sort operat
16840 69 6f 6e 73 20 77 68 65 6e 20 6d 75 6c 74 69 74  ions when multit
16850 68 72 65 61 64 65 64 20 73 6f 72 74 69 6e 67 0a  hreaded sorting.
16860 2a 2a 20 69 73 20 65 6e 61 62 6c 65 64 20 28 75  ** is enabled (u
16870 73 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  sing the [PRAGMA
16880 20 74 68 72 65 61 64 73 5d 20 63 6f 6d 6d 61 6e   threads] comman
16890 64 29 20 61 6e 64 20 74 68 65 20 61 6d 6f 75 6e  d) and the amoun
168a0 74 20 6f 66 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20  t of content.** 
168b0 74 6f 20 62 65 20 73 6f 72 74 65 64 20 65 78 63  to be sorted exc
168c0 65 65 64 73 20 74 68 65 20 70 61 67 65 20 73 69  eeds the page si
168d0 7a 65 20 74 69 6d 65 73 20 74 68 65 20 6d 69 6e  ze times the min
168e0 69 6d 75 6d 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  imum of the.** [
168f0 50 52 41 47 4d 41 20 63 61 63 68 65 5f 73 69 7a  PRAGMA cache_siz
16900 65 5d 20 73 65 74 74 69 6e 67 20 61 6e 64 20 74  e] setting and t
16910 68 69 73 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  his value..**.**
16920 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
16930 5f 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 5d  _STMTJRNL_SPILL]
16940 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
16950 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
16960 53 50 49 4c 4c 0a 2a 2a 20 3c 64 64 3e 5e 54 68  SPILL.** <dd>^Th
16970 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16980 53 54 4d 54 4a 52 4e 4c 5f 53 50 49 4c 4c 20 6f  STMTJRNL_SPILL o
16990 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
169a0 6e 67 6c 65 20 70 61 72 61 6d 65 74 65 72 20 77  ngle parameter w
169b0 68 69 63 68 0a 2a 2a 20 62 65 63 6f 6d 65 73 20  hich.** becomes 
169c0 74 68 65 20 5b 73 74 61 74 65 6d 65 6e 74 20 6a  the [statement j
169d0 6f 75 72 6e 61 6c 5d 20 73 70 69 6c 6c 2d 74 6f  ournal] spill-to
169e0 2d 64 69 73 6b 20 74 68 72 65 73 68 6f 6c 64 2e  -disk threshold.
169f0 20 20 0a 2a 2a 20 5b 53 74 61 74 65 6d 65 6e 74    .** [Statement
16a00 20 6a 6f 75 72 6e 61 6c 73 5d 20 61 72 65 20 68   journals] are h
16a10 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 75 6e  eld in memory un
16a20 74 69 6c 20 74 68 65 69 72 20 73 69 7a 65 20 28  til their size (
16a30 69 6e 20 62 79 74 65 73 29 0a 2a 2a 20 65 78 63  in bytes).** exc
16a40 65 65 64 73 20 74 68 69 73 20 74 68 72 65 73 68  eeds this thresh
16a50 6f 6c 64 2c 20 61 74 20 77 68 69 63 68 20 70 6f  old, at which po
16a60 69 6e 74 20 74 68 65 79 20 61 72 65 20 77 72 69  int they are wri
16a70 74 74 65 6e 20 74 6f 20 64 69 73 6b 2e 0a 2a 2a  tten to disk..**
16a80 20 4f 72 20 69 66 20 74 68 65 20 74 68 72 65 73   Or if the thres
16a90 68 6f 6c 64 20 69 73 20 2d 31 2c 20 73 74 61 74  hold is -1, stat
16aa0 65 6d 65 6e 74 20 6a 6f 75 72 6e 61 6c 73 20 61  ement journals a
16ab0 72 65 20 61 6c 77 61 79 73 20 68 65 6c 64 0a 2a  re always held.*
16ac0 2a 20 65 78 63 6c 75 73 69 76 65 6c 79 20 69 6e  * exclusively in
16ad0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 53 69 6e 63   memory..** Sinc
16ae0 65 20 6d 61 6e 79 20 73 74 61 74 65 6d 65 6e 74  e many statement
16af0 20 6a 6f 75 72 6e 61 6c 73 20 6e 65 76 65 72 20   journals never 
16b00 62 65 63 6f 6d 65 20 6c 61 72 67 65 2c 20 73 65  become large, se
16b10 74 74 69 6e 67 20 74 68 65 20 73 70 69 6c 6c 0a  tting the spill.
16b20 2a 2a 20 74 68 72 65 73 68 6f 6c 64 20 74 6f 20  ** threshold to 
16b30 61 20 76 61 6c 75 65 20 73 75 63 68 20 61 73 20  a value such as 
16b40 36 34 4b 69 42 20 63 61 6e 20 67 72 65 61 74 6c  64KiB can greatl
16b50 79 20 72 65 64 75 63 65 20 74 68 65 20 61 6d 6f  y reduce the amo
16b60 75 6e 74 20 6f 66 0a 2a 2a 20 49 2f 4f 20 72 65  unt of.** I/O re
16b70 71 75 69 72 65 64 20 74 6f 20 73 75 70 70 6f 72  quired to suppor
16b80 74 20 73 74 61 74 65 6d 65 6e 74 20 72 6f 6c 6c  t statement roll
16b90 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 64 65 66  back..** The def
16ba0 61 75 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74  ault value for t
16bb0 68 69 73 20 73 65 74 74 69 6e 67 20 69 73 20 63  his setting is c
16bc0 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 74 68 65  ontrolled by the
16bd0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 54 4d 54  .** [SQLITE_STMT
16be0 4a 52 4e 4c 5f 53 50 49 4c 4c 5d 20 63 6f 6d 70  JRNL_SPILL] comp
16bf0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
16c00 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
16c10 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
16c20 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
16c30 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
16c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
16c50 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
16c60 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
16c70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16c80 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
16c90 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
16ca0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
16cb0 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
16cc0 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
16cd0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
16ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
16cf0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
16d00 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
16d10 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
16d20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16d30 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
16d40 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
16d50 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
16d60 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
16d70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
16d80 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
16d90 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
16da0 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
16db0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
16dc0 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
16dd0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
16de0 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
16df0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16e00 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
16e10 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
16e20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16e30 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
16e40 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
16e50 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16e60 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
16e70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
16e80 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
16e90 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
16ea0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
16eb0 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
16ec0 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
16ed0 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
16ee0 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
16ef0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
16f00 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
16f10 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
16f20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16f30 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
16f40 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
16f50 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
16f60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16f70 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
16f80 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
16f90 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16fa0 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
16fb0 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
16fc0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
16fd0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
16fe0 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
16ff0 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
17000 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
17010 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
17020 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
17030 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
17040 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17050 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
17060 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
17070 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
17080 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17090 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
170a0 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
170b0 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
170c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
170d0 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
170e0 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
170f0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17100 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
17110 53 49 5a 45 20 20 20 20 32 32 20 20 2f 2a 20 73  SIZE    22  /* s
17120 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 20 73 71  qlite3_int64, sq
17130 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23  lite3_int64 */.#
17140 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17150 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53  NFIG_WIN32_HEAPS
17160 49 5a 45 20 20 20 20 20 20 32 33 20 20 2f 2a 20  IZE      23  /* 
17170 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 23 64 65  int nByte */.#de
17180 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17190 49 47 5f 50 43 41 43 48 45 5f 48 44 52 53 5a 20  IG_PCACHE_HDRSZ 
171a0 20 20 20 20 20 20 20 32 34 20 20 2f 2a 20 69 6e         24  /* in
171b0 74 20 2a 70 73 7a 20 2a 2f 0a 23 64 65 66 69 6e  t *psz */.#defin
171c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
171d0 50 4d 41 53 5a 20 20 20 20 20 20 20 20 20 20 20  PMASZ           
171e0 20 20 20 20 32 35 20 20 2f 2a 20 75 6e 73 69 67      25  /* unsig
171f0 6e 65 64 20 69 6e 74 20 73 7a 50 6d 61 20 2a 2f  ned int szPma */
17200 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17210 43 4f 4e 46 49 47 5f 53 54 4d 54 4a 52 4e 4c 5f  CONFIG_STMTJRNL_
17220 53 50 49 4c 4c 20 20 20 20 20 20 32 36 20 20 2f  SPILL      26  /
17230 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f 0a 0a  * int nByte */..
17240 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17250 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
17260 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
17270 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
17280 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
17290 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
172a0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
172b0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
172c0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
172d0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
172e0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
172f0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
17300 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
17310 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
17320 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
17330 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
17340 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
17350 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
17360 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
17370 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17380 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
17390 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
173a0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
173b0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
173c0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
173d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
173e0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
173f0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
17400 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
17410 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
17420 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
17430 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
17440 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
17450 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
17460 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
17470 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
17480 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
17490 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
174a0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
174b0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
174c0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
174d0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
174e0 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
174f0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17500 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
17510 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
17520 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
17530 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
17540 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
17550 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17560 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
17570 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
17580 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
17590 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
175a0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
175b0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
175c0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
175d0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
175e0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
175f0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
17600 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
17610 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
17620 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
17630 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
17640 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
17650 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
17660 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
17670 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
17680 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
17690 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
176a0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
176b0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
176c0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
176d0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
176e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
176f0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
17700 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
17710 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
17720 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
17730 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
17740 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
17750 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
17760 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
17770 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
17780 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
17790 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
177a0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
177b0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
177c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
177d0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
177e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
177f0 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
17800 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
17810 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
17820 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
17830 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
17840 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
17850 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
17860 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
17870 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
17880 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
17890 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
178a0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
178b0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
178c0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
178d0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
178e0 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
178f0 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
17900 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
17910 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
17920 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
17930 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
17940 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
17950 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
17960 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
17970 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
17980 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
17990 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
179a0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
179b0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
179c0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
179d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
179e0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
179f0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
17a00 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
17a10 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
17a20 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
17a30 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
17a40 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
17a50 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
17a60 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
17a70 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
17a80 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
17a90 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
17aa0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
17ab0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
17ac0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
17ad0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
17ae0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
17af0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
17b00 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
17b10 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
17b20 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
17b30 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
17b40 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
17b50 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
17b60 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
17b70 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
17b80 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
17b90 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
17ba0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
17bb0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
17bc0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
17bd0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
17be0 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
17bf0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
17c00 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17c10 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
17c20 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
17c30 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
17c40 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
17c50 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
17c60 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
17c70 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
17c80 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
17c90 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
17ca0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
17cb0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
17cc0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
17cd0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
17ce0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
17cf0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
17d00 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
17d10 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
17d20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
17d30 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
17d40 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
17d50 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
17d60 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
17d70 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
17d80 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
17d90 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
17da0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
17db0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17dc0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
17dd0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
17de0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
17df0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
17e00 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
17e10 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
17e20 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
17e30 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
17e40 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
17e50 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17e60 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
17e70 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
17e80 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
17e90 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
17ea0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
17eb0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
17ec0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
17ed0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 54 53 33  NFIG_ENABLE_FTS3
17ee0 5f 54 4f 4b 45 4e 49 5a 45 52 3c 2f 64 74 3e 0a  _TOKENIZER</dt>.
17ef0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
17f00 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
17f10 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
17f20 65 20 74 68 65 20 74 77 6f 2d 61 72 67 75 6d 65  e the two-argume
17f30 6e 74 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66  nt.** version of
17f40 20 74 68 65 20 5b 66 74 73 33 5f 74 6f 6b 65 6e   the [fts3_token
17f50 69 7a 65 72 28 29 5d 20 66 75 6e 63 74 69 6f 6e  izer()] function
17f60 20 77 68 69 63 68 20 69 73 20 70 61 72 74 20 6f   which is part o
17f70 66 20 74 68 65 0a 2a 2a 20 5b 46 54 53 33 5d 20  f the.** [FTS3] 
17f80 66 75 6c 6c 2d 74 65 78 74 20 73 65 61 72 63 68  full-text search
17f90 20 65 6e 67 69 6e 65 20 65 78 74 65 6e 73 69 6f   engine extensio
17fa0 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  n..** There shou
17fb0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
17fc0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
17fd0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
17fe0 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
17ff0 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
18000 6f 20 64 69 73 61 62 6c 65 20 66 74 73 33 5f 74  o disable fts3_t
18010 6f 6b 65 6e 69 7a 65 72 28 29 20 6f 72 0a 2a 2a  okenizer() or.**
18020 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61   positive to ena
18030 62 6c 65 20 66 74 73 33 5f 74 6f 6b 65 6e 69 7a  ble fts3_tokeniz
18040 65 72 28 29 20 6f 72 20 6e 65 67 61 74 69 76 65  er() or negative
18050 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
18060 74 74 69 6e 67 0a 2a 2a 20 75 6e 63 68 61 6e 67  tting.** unchang
18070 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
18080 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18090 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
180a0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
180b0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
180c0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
180d0 74 65 20 77 68 65 74 68 65 72 20 66 74 73 33 5f  te whether fts3_
180e0 74 6f 6b 65 6e 69 7a 65 72 20 69 73 20 64 69 73  tokenizer is dis
180f0 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64  abled or enabled
18100 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
18110 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
18120 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
18130 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
18140 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
18150 68 20 63 61 73 65 20 74 68 65 20 6e 65 77 20 73  h case the new s
18160 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65  etting is not re
18170 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64  ported back. </d
18180 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18190 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
181a0 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45 4e 53 49  BLE_LOAD_EXTENSI
181b0 4f 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ON</dt>.** <dd> 
181c0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
181d0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
181e0 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 5b 73  r disable the [s
181f0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
18200 6e 73 69 6f 6e 28 29 5d 0a 2a 2a 20 69 6e 74 65  nsion()].** inte
18210 72 66 61 63 65 20 69 6e 64 65 70 65 6e 64 65 6e  rface independen
18220 74 6c 79 20 6f 66 20 74 68 65 20 5b 6c 6f 61 64  tly of the [load
18230 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 53 51  _extension()] SQ
18240 4c 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  L function..** T
18250 68 65 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62  he [sqlite3_enab
18260 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
18270 6e 28 29 5d 20 41 50 49 20 65 6e 61 62 6c 65 73  n()] API enables
18280 20 6f 72 20 64 69 73 61 62 6c 65 73 20 62 6f 74   or disables bot
18290 68 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 5b  h the.** C-API [
182a0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
182b0 65 6e 73 69 6f 6e 28 29 5d 20 61 6e 64 20 74 68  ension()] and th
182c0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 5b  e SQL function [
182d0 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29  load_extension()
182e0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
182f0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
18300 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
18310 2a 2a 20 57 68 65 6e 20 74 68 65 20 66 69 72 73  ** When the firs
18320 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
18330 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
18340 31 2c 20 74 68 65 6e 20 6f 6e 6c 79 20 74 68 65  1, then only the
18350 20 43 2d 41 50 49 20 69 73 0a 2a 2a 20 65 6e 61   C-API is.** ena
18360 62 6c 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  bled and the SQL
18370 20 66 75 6e 63 74 69 6f 6e 20 72 65 6d 61 69 6e   function remain
18380 73 20 64 69 73 61 62 6c 65 64 2e 20 20 49 66 20  s disabled.  If 
18390 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
183a0 6e 74 20 74 6f 0a 2a 2a 20 74 68 69 73 20 69 6e  nt to.** this in
183b0 74 65 72 66 61 63 65 20 69 73 20 30 2c 20 74 68  terface is 0, th
183c0 65 6e 20 62 6f 74 68 20 74 68 65 20 43 2d 41 50  en both the C-AP
183d0 49 20 61 6e 64 20 74 68 65 20 53 51 4c 20 66 75  I and the SQL fu
183e0 6e 63 74 69 6f 6e 20 61 72 65 20 64 69 73 61 62  nction are disab
183f0 6c 65 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  led..** If the f
18400 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
18410 20 2d 31 2c 20 74 68 65 6e 20 6e 6f 20 63 68 61   -1, then no cha
18420 6e 67 65 73 20 61 72 65 20 6d 61 64 65 20 74 6f  nges are made to
18430 20 73 74 61 74 65 20 6f 66 20 65 69 74 68 65 72   state of either
18440 20 74 68 65 0a 2a 2a 20 43 2d 41 50 49 20 6f 72   the.** C-API or
18450 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
18460 6e 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  n..** The second
18470 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
18480 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
18490 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
184a0 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
184b0 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
184c0 65 20 77 68 65 74 68 65 72 20 5b 73 71 6c 69 74  e whether [sqlit
184d0 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  e3_load_extensio
184e0 6e 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  n()] interface.*
184f0 2a 20 69 73 20 64 69 73 61 62 6c 65 64 20 6f 72  * is disabled or
18500 20 65 6e 61 62 6c 65 64 20 66 6f 6c 6c 6f 77 69   enabled followi
18510 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
18520 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
18530 74 65 72 20 6d 61 79 0a 2a 2a 20 62 65 20 61 20  ter may.** be a 
18540 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
18550 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
18560 6e 65 77 20 73 65 74 74 69 6e 67 20 69 73 20 6e  new setting is n
18570 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
18580 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
18590 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
185a0 4e 46 49 47 5f 4d 41 49 4e 44 42 4e 41 4d 45 3c  NFIG_MAINDBNAME<
185b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
185c0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
185d0 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  d to change the 
185e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 22 6d 61 69  name of the "mai
185f0 6e 22 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 73  n" database.** s
18600 63 68 65 6d 61 2e 20 20 5e 54 68 65 20 73 6f 6c  chema.  ^The sol
18610 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
18620 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 63 6f 6e  pointer to a con
18630 73 74 61 6e 74 20 55 54 46 38 20 73 74 72 69 6e  stant UTF8 strin
18640 67 0a 2a 2a 20 77 68 69 63 68 20 77 69 6c 6c 20  g.** which will 
18650 62 65 63 6f 6d 65 20 74 68 65 20 6e 65 77 20 73  become the new s
18660 63 68 65 6d 61 20 6e 61 6d 65 20 69 6e 20 70 6c  chema name in pl
18670 61 63 65 20 6f 66 20 22 6d 61 69 6e 22 2e 20 20  ace of "main".  
18680 5e 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20  ^SQLite.** does 
18690 6e 6f 74 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  not make a copy 
186a0 6f 66 20 74 68 65 20 6e 65 77 20 6d 61 69 6e 20  of the new main 
186b0 73 63 68 65 6d 61 20 6e 61 6d 65 20 73 74 72 69  schema name stri
186c0 6e 67 2c 20 73 6f 20 74 68 65 20 61 70 70 6c 69  ng, so the appli
186d0 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 65  cation.** must e
186e0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 61  nsure that the a
186f0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
18700 6e 74 6f 20 74 68 69 73 20 44 42 43 4f 4e 46 49  nto this DBCONFI
18710 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 63 68  G option is unch
18720 61 6e 67 65 64 0a 2a 2a 20 75 6e 74 69 6c 20 61  anged.** until a
18730 66 74 65 72 20 74 68 65 20 64 61 74 61 62 61 73  fter the databas
18740 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
18750 73 65 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ses..** </dd>.**
18760 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
18770 42 43 4f 4e 46 49 47 5f 4e 4f 5f 43 4b 50 54 5f  BCONFIG_NO_CKPT_
18780 4f 4e 5f 43 4c 4f 53 45 3c 2f 64 74 3e 0a 2a 2a  ON_CLOSE</dt>.**
18790 20 3c 64 64 3e 20 55 73 75 61 6c 6c 79 2c 20 77   <dd> Usually, w
187a0 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 69  hen a database i
187b0 6e 20 77 61 6c 20 6d 6f 64 65 20 69 73 20 63 6c  n wal mode is cl
187c0 6f 73 65 64 20 6f 72 20 64 65 74 61 63 68 65 64  osed or detached
187d0 20 66 72 6f 6d 20 61 20 0a 2a 2a 20 64 61 74 61   from a .** data
187e0 62 61 73 65 20 68 61 6e 64 6c 65 2c 20 53 51 4c  base handle, SQL
187f0 69 74 65 20 63 68 65 63 6b 73 20 69 66 20 74 68  ite checks if th
18800 69 73 20 77 69 6c 6c 20 6d 65 61 6e 20 74 68 61  is will mean tha
18810 74 20 74 68 65 72 65 20 61 72 65 20 6e 6f 77 20  t there are now 
18820 6e 6f 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  no .** connectio
18830 6e 73 20 61 74 20 61 6c 6c 20 74 6f 20 74 68 65  ns at all to the
18840 20 64 61 74 61 62 61 73 65 2e 20 49 66 20 73 6f   database. If so
18850 2c 20 69 74 20 70 65 72 66 6f 72 6d 73 20 61 20  , it performs a 
18860 63 68 65 63 6b 70 6f 69 6e 74 20 0a 2a 2a 20 6f  checkpoint .** o
18870 70 65 72 61 74 69 6f 6e 20 62 65 66 6f 72 65 20  peration before 
18880 63 6c 6f 73 69 6e 67 20 74 68 65 20 63 6f 6e 6e  closing the conn
18890 65 63 74 69 6f 6e 2e 20 54 68 69 73 20 6f 70 74  ection. This opt
188a0 69 6f 6e 20 6d 61 79 20 62 65 20 75 73 65 64 20  ion may be used 
188b0 74 6f 0a 2a 2a 20 6f 76 65 72 72 69 64 65 20 74  to.** override t
188c0 68 69 73 20 62 65 68 61 76 69 6f 75 72 2e 20 54  his behaviour. T
188d0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
188e0 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 69  er passed to thi
188f0 73 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 69  s operation.** i
18900 73 20 61 6e 20 69 6e 74 65 67 65 72 20 2d 20 6e  s an integer - n
18910 6f 6e 2d 7a 65 72 6f 20 74 6f 20 64 69 73 61 62  on-zero to disab
18920 6c 65 20 63 68 65 63 6b 70 6f 69 6e 74 73 2d 6f  le checkpoints-o
18930 6e 2d 63 6c 6f 73 65 2c 20 6f 72 20 7a 65 72 6f  n-close, or zero
18940 20 28 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74   (the.** default
18950 29 20 74 6f 20 65 6e 61 62 6c 65 20 74 68 65 6d  ) to enable them
18960 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  . The second par
18970 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
18980 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
18990 72 0a 2a 2a 20 69 6e 74 6f 20 77 68 69 63 68 20  r.** into which 
189a0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
189b0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
189c0 65 74 68 65 72 20 63 68 65 63 6b 70 6f 69 6e 74  ether checkpoint
189d0 73 2d 6f 6e 2d 63 6c 6f 73 65 0a 2a 2a 20 68 61  s-on-close.** ha
189e0 76 65 20 62 65 65 6e 20 64 69 73 61 62 6c 65 64  ve been disabled
189f0 20 2d 20 30 20 69 66 20 74 68 65 79 20 61 72 65   - 0 if they are
18a00 20 6e 6f 74 20 64 69 73 61 62 6c 65 64 2c 20 31   not disabled, 1
18a10 20 69 66 20 74 68 65 79 20 61 72 65 2e 0a 2a 2a   if they are..**
18a20 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64   </dd>.**.** </d
18a30 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
18a40 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4d 41  LITE_DBCONFIG_MA
18a50 49 4e 44 42 4e 41 4d 45 20 20 20 20 20 20 20 20  INDBNAME        
18a60 20 20 20 20 31 30 30 30 20 2f 2a 20 63 6f 6e 73      1000 /* cons
18a70 74 20 63 68 61 72 2a 20 2a 2f 0a 23 64 65 66 69  t char* */.#defi
18a80 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
18a90 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
18aa0 20 20 20 20 20 20 20 20 20 31 30 30 31 20 2f 2a           1001 /*
18ab0 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
18ac0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18ad0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
18ae0 5f 46 4b 45 59 20 20 20 20 20 20 20 20 20 20 20  _FKEY           
18af0 31 30 30 32 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  1002 /* int int*
18b00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18b10 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
18b20 4c 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  LE_TRIGGER      
18b30 20 20 31 30 30 33 20 2f 2a 20 69 6e 74 20 69 6e    1003 /* int in
18b40 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18b50 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18b60 41 42 4c 45 5f 46 54 53 33 5f 54 4f 4b 45 4e 49  ABLE_FTS3_TOKENI
18b70 5a 45 52 20 31 30 30 34 20 2f 2a 20 69 6e 74 20  ZER 1004 /* int 
18b80 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  int* */.#define 
18b90 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
18ba0 45 4e 41 42 4c 45 5f 4c 4f 41 44 5f 45 58 54 45  ENABLE_LOAD_EXTE
18bb0 4e 53 49 4f 4e 20 31 30 30 35 20 2f 2a 20 69 6e  NSION 1005 /* in
18bc0 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
18bd0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
18be0 47 5f 4e 4f 5f 43 4b 50 54 5f 4f 4e 5f 43 4c 4f  G_NO_CKPT_ON_CLO
18bf0 53 45 20 20 20 20 20 20 31 30 30 36 20 2f 2a 20  SE      1006 /* 
18c00 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
18c10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
18c20 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
18c30 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
18c40 43 6f 64 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  Codes.** METHOD:
18c50 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e   sqlite3.**.** ^
18c60 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
18c70 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
18c80 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62  s() routine enab
18c90 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
18ca0 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  the.** [extended
18cb0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66   result codes] f
18cc0 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65  eature of SQLite
18cd0 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20  . ^The extended 
18ce0 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20  result.** codes 
18cf0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
18d00 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74  default for hist
18d10 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
18d20 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  lity..*/.int sql
18d30 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
18d40 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
18d50 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
18d60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18d70 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
18d80 77 69 64 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  wid.** METHOD: s
18d90 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 45 61  qlite3.**.** ^Ea
18da0 63 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74  ch entry in most
18db0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28   SQLite tables (
18dc0 65 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48  except for [WITH
18dd0 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65  OUT ROWID] table
18de0 73 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71  s).** has a uniq
18df0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
18e00 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
18e10 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
18e20 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
18e30 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
18e40 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
18e50 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
18e60 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
18e70 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
18e80 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
18e90 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
18ea0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
18eb0 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
18ec0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
18ed0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
18ee0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
18ef0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
18f00 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
18f10 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
18f20 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
18f30 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
18f40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
18f50 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
18f60 72 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61  rowid(D) interfa
18f70 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b  ce returns the [
18f80 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a  rowid] of the .*
18f90 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75  * most recent su
18fa0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
18fb0 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74  ] into a rowid t
18fc0 61 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c  able or [virtual
18fd0 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61   table].** on da
18fe0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18ff0 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73  n D..** ^Inserts
19000 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52   into [WITHOUT R
19010 4f 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65  OWID] tables are
19020 20 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a   not recorded..*
19030 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
19040 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e  ful [INSERT]s in
19050 74 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a  to rowid tables.
19060 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
19070 75 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74  urred on the dat
19080 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19090 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c   D, .** then sql
190a0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
190b0 5f 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e  _rowid(D) return
190c0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28  s zero..**.** ^(
190d0 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
190e0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
190f0 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
19100 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
19110 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
19120 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
19130 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
19140 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
19150 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
19160 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
19170 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
19180 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
19190 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
191a0 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
191b0 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
191c0 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
191d0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
191e0 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
191f0 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
19200 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
19210 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
19220 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
19230 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
19240 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
19250 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
19260 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
19270 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
19280 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
19290 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
192a0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
192b0 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
192c0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
192d0 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
192e0 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
192f0 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
19300 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
19310 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
19320 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
19330 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
19340 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
19350 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
19360 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
19370 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
19380 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
19390 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
193a0 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
193b0 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
193c0 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
193d0 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
193e0 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
193f0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
19400 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
19410 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
19420 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
19430 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
19440 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
19450 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
19460 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
19470 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
19480 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
19490 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
194a0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
194b0 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
194c0 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
194d0 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
194e0 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
194f0 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
19500 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
19510 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
19520 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
19530 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
19540 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
19550 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
19560 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
19570 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
19580 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
19590 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
195a0 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
195b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
195c0 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
195d0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
195e0 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
195f0 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
19600 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
19610 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
19620 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
19630 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19640 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
19650 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19660 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
19670 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
19680 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
19690 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
196a0 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
196b0 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
196c0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
196d0 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
196e0 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
196f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
19700 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
19710 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
19720 64 69 66 69 65 64 0a 2a 2a 20 4d 45 54 48 4f 44  dified.** METHOD
19730 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
19740 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
19750 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
19760 72 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69  r of rows modifi
19770 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 0a  ed, inserted or.
19780 2a 2a 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  ** deleted by th
19790 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
197a0 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
197b0 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c 45  , UPDATE or DELE
197c0 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
197d0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
197e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 70 65 63 69  connection speci
197f0 66 69 65 64 20 62 79 20 74 68 65 20 6f 6e 6c 79  fied by the only
19800 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
19810 45 78 65 63 75 74 69 6e 67 20 61 6e 79 20 6f 74  Executing any ot
19820 68 65 72 20 74 79 70 65 20 6f 66 20 53 51 4c 20  her type of SQL 
19830 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
19840 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 76 61  ot modify the va
19850 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
19860 62 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  by this function
19870 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 63 68  ..**.** ^Only ch
19880 61 6e 67 65 73 20 6d 61 64 65 20 64 69 72 65 63  anges made direc
19890 74 6c 79 20 62 79 20 74 68 65 20 49 4e 53 45 52  tly by the INSER
198a0 54 2c 20 55 50 44 41 54 45 20 6f 72 20 44 45 4c  T, UPDATE or DEL
198b0 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 61 72  ETE statement ar
198c0 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
198d0 2d 20 61 75 78 69 6c 69 61 72 79 20 63 68 61 6e  - auxiliary chan
198e0 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 43  ges caused by [C
198f0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
19900 74 72 69 67 67 65 72 73 5d 2c 20 0a 2a 2a 20 5b  triggers], .** [
19910 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
19920 6f 6e 73 5d 20 6f 72 20 5b 52 45 50 4c 41 43 45  ons] or [REPLACE
19930 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
19940 6f 6c 75 74 69 6f 6e 20 61 72 65 20 6e 6f 74 20  olution are not 
19950 63 6f 75 6e 74 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  counted..** .** 
19960 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65  Changes to a vie
19970 77 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  w that are inter
19980 63 65 70 74 65 64 20 62 79 20 0a 2a 2a 20 5b 49  cepted by .** [I
19990 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
199a0 72 20 7c 20 49 4e 53 54 45 41 44 20 4f 46 20 74  r | INSTEAD OF t
199b0 72 69 67 67 65 72 73 5d 20 61 72 65 20 6e 6f 74  riggers] are not
199c0 20 63 6f 75 6e 74 65 64 2e 20 5e 54 68 65 20 76   counted. ^The v
199d0 61 6c 75 65 20 0a 2a 2a 20 72 65 74 75 72 6e 65  alue .** returne
199e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 68 61  d by sqlite3_cha
199f0 6e 67 65 73 28 29 20 69 6d 6d 65 64 69 61 74 65  nges() immediate
19a00 6c 79 20 61 66 74 65 72 20 61 6e 20 49 4e 53 45  ly after an INSE
19a10 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20 0a 2a  RT, UPDATE or .*
19a20 2a 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  * DELETE stateme
19a30 6e 74 20 72 75 6e 20 6f 6e 20 61 20 76 69 65 77  nt run on a view
19a40 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2e   is always zero.
19a50 20 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 6d 61   Only changes ma
19a60 64 65 20 74 6f 20 72 65 61 6c 20 0a 2a 2a 20 74  de to real .** t
19a70 61 62 6c 65 73 20 61 72 65 20 63 6f 75 6e 74 65  ables are counte
19a80 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 67 73 20  d..**.** Things 
19a90 61 72 65 20 6d 6f 72 65 20 63 6f 6d 70 6c 69 63  are more complic
19aa0 61 74 65 64 20 69 66 20 74 68 65 20 73 71 6c 69  ated if the sqli
19ab0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 66 75  te3_changes() fu
19ac0 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 65 78 65  nction is.** exe
19ad0 63 75 74 65 64 20 77 68 69 6c 65 20 61 20 74 72  cuted while a tr
19ae0 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 69 73  igger program is
19af0 20 72 75 6e 6e 69 6e 67 2e 20 54 68 69 73 20 6d   running. This m
19b00 61 79 20 68 61 70 70 65 6e 20 69 66 20 74 68 65  ay happen if the
19b10 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 65 73  .** program uses
19b20 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
19b30 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2c 20 6f  SQL function], o
19b40 72 20 69 66 20 73 6f 6d 65 20 6f 74 68 65 72 20  r if some other 
19b50 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
19b60 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20 73 71 6c  tion invokes sql
19b70 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 64  ite3_changes() d
19b80 69 72 65 63 74 6c 79 2e 20 45 73 73 65 6e 74 69  irectly. Essenti
19b90 61 6c 6c 79 3a 0a 2a 2a 20 0a 2a 2a 20 3c 75 6c  ally:.** .** <ul
19ba0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5e 28 42 65  >.**   <li> ^(Be
19bb0 66 6f 72 65 20 65 6e 74 65 72 69 6e 67 20 61 20  fore entering a 
19bc0 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20  trigger program 
19bd0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
19be0 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20 20  ed by.**        
19bf0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
19c00 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 73 61  ) function is sa
19c10 76 65 64 2e 20 41 66 74 65 72 20 74 68 65 20 74  ved. After the t
19c20 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d 20 0a  rigger program .
19c30 2a 2a 20 20 20 20 20 20 20 20 68 61 73 20 66 69  **        has fi
19c40 6e 69 73 68 65 64 2c 20 74 68 65 20 6f 72 69 67  nished, the orig
19c50 69 6e 61 6c 20 76 61 6c 75 65 20 69 73 20 72 65  inal value is re
19c60 73 74 6f 72 65 64 2e 29 5e 0a 2a 2a 20 0a 2a 2a  stored.)^.** .**
19c70 20 20 20 3c 6c 69 3e 20 5e 28 57 69 74 68 69 6e     <li> ^(Within
19c80 20 61 20 74 72 69 67 67 65 72 20 70 72 6f 67 72   a trigger progr
19c90 61 6d 20 65 61 63 68 20 49 4e 53 45 52 54 2c 20  am each INSERT, 
19ca0 55 50 44 41 54 45 20 61 6e 64 20 44 45 4c 45 54  UPDATE and DELET
19cb0 45 20 0a 2a 2a 20 20 20 20 20 20 20 20 73 74 61  E .**        sta
19cc0 74 65 6d 65 6e 74 20 73 65 74 73 20 74 68 65 20  tement sets the 
19cd0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
19ce0 79 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  y sqlite3_change
19cf0 73 28 29 20 0a 2a 2a 20 20 20 20 20 20 20 20 75  s() .**        u
19d00 70 6f 6e 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61  pon completion a
19d10 73 20 6e 6f 72 6d 61 6c 2e 20 4f 66 20 63 6f 75  s normal. Of cou
19d20 72 73 65 2c 20 74 68 69 73 20 76 61 6c 75 65 20  rse, this value 
19d30 77 69 6c 6c 20 6e 6f 74 20 69 6e 63 6c 75 64 65  will not include
19d40 20 0a 2a 2a 20 20 20 20 20 20 20 20 61 6e 79 20   .**        any 
19d50 63 68 61 6e 67 65 73 20 70 65 72 66 6f 72 6d 65  changes performe
19d60 64 20 62 79 20 73 75 62 2d 74 72 69 67 67 65 72  d by sub-trigger
19d70 73 2c 20 61 73 20 74 68 65 20 73 71 6c 69 74 65  s, as the sqlite
19d80 33 5f 63 68 61 6e 67 65 73 28 29 20 0a 2a 2a 20  3_changes() .** 
19d90 20 20 20 20 20 20 20 76 61 6c 75 65 20 77 69 6c         value wil
19da0 6c 20 62 65 20 73 61 76 65 64 20 61 6e 64 20 72  l be saved and r
19db0 65 73 74 6f 72 65 64 20 61 66 74 65 72 20 65 61  estored after ea
19dc0 63 68 20 73 75 62 2d 74 72 69 67 67 65 72 20 68  ch sub-trigger h
19dd0 61 73 20 72 75 6e 2e 29 5e 0a 2a 2a 20 3c 2f 75  as run.)^.** </u
19de0 6c 3e 0a 2a 2a 20 0a 2a 2a 20 5e 54 68 69 73 20  l>.** .** ^This 
19df0 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20 74 68  means that if th
19e00 65 20 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  e changes() SQL 
19e10 66 75 6e 63 74 69 6f 6e 20 28 6f 72 20 73 69 6d  function (or sim
19e20 69 6c 61 72 29 20 69 73 20 75 73 65 64 0a 2a 2a  ilar) is used.**
19e30 20 62 79 20 74 68 65 20 66 69 72 73 74 20 49 4e   by the first IN
19e40 53 45 52 54 2c 20 55 50 44 41 54 45 20 6f 72 20  SERT, UPDATE or 
19e50 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
19e60 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
19e70 72 2c 20 69 74 20 0a 2a 2a 20 72 65 74 75 72 6e  r, it .** return
19e80 73 20 74 68 65 20 76 61 6c 75 65 20 61 73 20 73  s the value as s
19e90 65 74 20 77 68 65 6e 20 74 68 65 20 63 61 6c 6c  et when the call
19ea0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 62 65  ing statement be
19eb0 67 61 6e 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a  gan executing..*
19ec0 2a 20 5e 49 66 20 69 74 20 69 73 20 75 73 65 64  * ^If it is used
19ed0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 6f   by the second o
19ee0 72 20 73 75 62 73 65 71 75 65 6e 74 20 73 75 63  r subsequent suc
19ef0 68 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  h statement with
19f00 69 6e 20 61 20 74 72 69 67 67 65 72 20 0a 2a 2a  in a trigger .**
19f10 20 70 72 6f 67 72 61 6d 2c 20 74 68 65 20 76 61   program, the va
19f20 6c 75 65 20 72 65 74 75 72 6e 65 64 20 72 65 66  lue returned ref
19f30 6c 65 63 74 73 20 74 68 65 20 6e 75 6d 62 65 72  lects the number
19f40 20 6f 66 20 72 6f 77 73 20 6d 6f 64 69 66 69 65   of rows modifie
19f50 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 70 72 65  d by the .** pre
19f60 76 69 6f 75 73 20 49 4e 53 45 52 54 2c 20 55 50  vious INSERT, UP
19f70 44 41 54 45 20 6f 72 20 44 45 4c 45 54 45 20 73  DATE or DELETE s
19f80 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
19f90 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
19fa0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
19fb0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f   the [sqlite3_to
19fc0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
19fd0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
19fe0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
19ff0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
1a000 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20   [changes() SQL 
1a010 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1a020 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1a030 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1a040 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1a050 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a060 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1a070 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
1a080 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e   is running then
1a090 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
1a0a0 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64  ned.** is unpred
1a0b0 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20  ictable and not 
1a0c0 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69  meaningful..*/.i
1a0d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
1a0e0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
1a0f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1a100 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
1a110 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 20  ows Modified.** 
1a120 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
1a130 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1a140 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1a150 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
1a160 20 72 6f 77 73 20 69 6e 73 65 72 74 65 64 2c 20   rows inserted, 
1a170 6d 6f 64 69 66 69 65 64 20 6f 72 0a 2a 2a 20 64  modified or.** d
1a180 65 6c 65 74 65 64 20 62 79 20 61 6c 6c 20 5b 49  eleted by all [I
1a190 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
1a1a0 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61   or [DELETE] sta
1a1b0 74 65 6d 65 6e 74 73 20 63 6f 6d 70 6c 65 74 65  tements complete
1a1c0 64 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 64  d.** since the d
1a1d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a1e0 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20 69  on was opened, i
1a1f0 6e 63 6c 75 64 69 6e 67 20 74 68 6f 73 65 20 65  ncluding those e
1a200 78 65 63 75 74 65 64 20 61 73 0a 2a 2a 20 70 61  xecuted as.** pa
1a210 72 74 20 6f 66 20 74 72 69 67 67 65 72 20 70 72  rt of trigger pr
1a220 6f 67 72 61 6d 73 2e 20 5e 45 78 65 63 75 74 69  ograms. ^Executi
1a230 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 74 79 70  ng any other typ
1a240 65 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  e of SQL stateme
1a250 6e 74 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 61  nt.** does not a
1a260 66 66 65 63 74 20 74 68 65 20 76 61 6c 75 65 20  ffect the value 
1a270 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1a280 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1a290 73 28 29 2e 0a 2a 2a 20 0a 2a 2a 20 5e 43 68 61  s()..** .** ^Cha
1a2a0 6e 67 65 73 20 6d 61 64 65 20 61 73 20 70 61 72  nges made as par
1a2b0 74 20 6f 66 20 5b 66 6f 72 65 69 67 6e 20 6b 65  t of [foreign ke
1a2c0 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 69  y actions] are i
1a2d0 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 2a  ncluded in the.*
1a2e0 2a 20 63 6f 75 6e 74 2c 20 62 75 74 20 74 68 6f  * count, but tho
1a2f0 73 65 20 6d 61 64 65 20 61 73 20 70 61 72 74 20  se made as part 
1a300 6f 66 20 52 45 50 4c 41 43 45 20 63 6f 6e 73 74  of REPLACE const
1a310 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e  raint resolution
1a320 20 61 72 65 0a 2a 2a 20 6e 6f 74 2e 20 5e 43 68   are.** not. ^Ch
1a330 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
1a340 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 63 65  that are interce
1a350 70 74 65 64 20 62 79 20 49 4e 53 54 45 41 44 20  pted by INSTEAD 
1a360 4f 46 20 74 72 69 67 67 65 72 73 20 0a 2a 2a 20  OF triggers .** 
1a370 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e  are not counted.
1a380 0a 2a 2a 20 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  .** .** See also
1a390 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68   the [sqlite3_ch
1a3a0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
1a3b0 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
1a3c0 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
1a3d0 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61  ], and the [tota
1a3e0 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20  l_changes() SQL 
1a3f0 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a  function]..**.**
1a400 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74   If a separate t
1a410 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e  hread makes chan
1a420 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ges on the same 
1a430 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a440 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71  ion.** while [sq
1a450 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1a460 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e  ges()] is runnin
1a470 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  g then the value
1a480 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20  .** returned is 
1a490 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
1a4a0 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c  d not meaningful
1a4b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1a4c0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
1a4d0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1a4e0 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
1a4f0 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
1a500 69 6e 67 20 51 75 65 72 79 0a 2a 2a 20 4d 45 54  ing Query.** MET
1a510 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1a520 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1a530 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
1a540 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
1a550 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
1a560 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
1a570 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
1a580 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
1a590 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
1a5a0 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
1a5b0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
1a5c0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
1a5d0 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
1a5e0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
1a5f0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
1a600 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
1a610 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
1a620 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
1a630 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
1a640 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
1a650 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
1a660 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
1a670 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
1a680 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
1a690 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
1a6a0 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
1a6b0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
1a6c0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
1a6d0 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1a6e0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
1a6f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a700 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
1a710 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
1a720 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
1a730 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1a740 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1a750 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
1a760 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
1a770 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
1a780 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
1a790 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1a7a0 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
1a7b0 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
1a7c0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
1a7d0 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
1a7e0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
1a7f0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
1a800 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
1a810 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
1a820 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
1a830 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
1a840 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
1a850 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
1a860 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
1a870 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1a880 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1a890 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
1a8a0 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
1a8b0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
1a8c0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
1a8d0 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
1a8e0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
1a8f0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
1a900 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
1a910 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
1a920 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
1a930 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
1a940 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
1a950 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1a960 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
1a970 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a980 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
1a990 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
1a9a0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1a9b0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1a9c0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1a9d0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1a9e0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
1a9f0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
1aa00 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
1aa10 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
1aa20 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
1aa30 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
1aa40 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
1aa50 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1aa60 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
1aa70 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1aa80 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1aa90 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
1aaa0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
1aab0 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
1aac0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
1aad0 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
1aae0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
1aaf0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
1ab00 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1ab10 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
1ab20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
1ab30 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
1ab40 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
1ab50 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
1ab60 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
1ab70 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1ab80 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1ab90 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1aba0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1abb0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
1abc0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1abd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
1abe0 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
1abf0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
1ac00 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
1ac10 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
1ac20 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
1ac30 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
1ac40 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
1ac50 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
1ac60 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
1ac70 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
1ac80 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
1ac90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1aca0 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
1acb0 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
1acc0 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
1acd0 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
1ace0 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
1acf0 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
1ad00 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
1ad10 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1ad20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
1ad30 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
1ad40 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
1ad50 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
1ad60 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
1ad70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
1ad80 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1ad90 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
1ada0 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
1adb0 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
1adc0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
1add0 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
1ade0 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
1adf0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
1ae00 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
1ae10 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
1ae20 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
1ae30 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
1ae40 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
1ae50 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
1ae60 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
1ae70 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
1ae80 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
1ae90 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
1aea0 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
1aeb0 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
1aec0 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
1aed0 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
1aee0 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
1aef0 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
1af00 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
1af10 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
1af20 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
1af30 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
1af40 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
1af50 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
1af60 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
1af70 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
1af80 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
1af90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
1afa0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
1afb0 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
1afc0 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
1afd0 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
1afe0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
1aff0 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
1b000 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
1b010 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1b020 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
1b030 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
1b040 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
1b050 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
1b060 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
1b070 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
1b080 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
1b090 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
1b0a0 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
1b0b0 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
1b0c0 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
1b0d0 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
1b0e0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1b0f0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
1b100 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
1b110 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
1b120 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
1b130 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
1b140 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
1b150 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
1b160 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
1b170 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
1b180 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1b190 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
1b1a0 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
1b1b0 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
1b1c0 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
1b1d0 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
1b1e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
1b1f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
1b200 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
1b210 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1b220 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
1b230 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
1b240 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
1b250 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
1b260 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
1b270 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
1b280 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
1b290 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
1b2a0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
1b2b0 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
1b2c0 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
1b2d0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1b2e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
1b2f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b300 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
1b310 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
1b320 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
1b330 6f 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ors.** KEYWORDS:
1b340 20 7b 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63   {busy-handler c
1b350 61 6c 6c 62 61 63 6b 7d 20 7b 62 75 73 79 20 68  allback} {busy h
1b360 61 6e 64 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  andler}.** METHO
1b370 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1b380 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75   ^The sqlite3_bu
1b390 73 79 5f 68 61 6e 64 6c 65 72 28 44 2c 58 2c 50  sy_handler(D,X,P
1b3a0 29 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  ) routine sets a
1b3b0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1b3c0 6f 6e 20 58 0a 2a 2a 20 74 68 61 74 20 6d 69 67  on X.** that mig
1b3d0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1b3e0 74 68 20 61 72 67 75 6d 65 6e 74 20 50 20 77 68  th argument P wh
1b3f0 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
1b400 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
1b410 61 63 63 65 73 73 20 61 20 64 61 74 61 62 61 73  access a databas
1b420 65 20 74 61 62 6c 65 20 61 73 73 6f 63 69 61 74  e table associat
1b430 65 64 20 77 69 74 68 0a 2a 2a 20 5b 64 61 74 61  ed with.** [data
1b440 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1b450 20 44 20 77 68 65 6e 20 61 6e 6f 74 68 65 72 20   D when another 
1b460 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
1b470 63 65 73 73 20 68 61 73 20 74 68 65 20 74 61 62  cess has the tab
1b480 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 20 54 68  le locked..** Th
1b490 65 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  e sqlite3_busy_h
1b4a0 61 6e 64 6c 65 72 28 29 20 69 6e 74 65 72 66 61  andler() interfa
1b4b0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 69 6d  ce is used to im
1b4c0 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b 73 71 6c 69  plement.** [sqli
1b4d0 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
1b4e0 28 29 5d 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  ()] and [PRAGMA 
1b4f0 62 75 73 79 5f 74 69 6d 65 6f 75 74 5d 2e 0a 2a  busy_timeout]..*
1b500 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
1b510 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1b520 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
1b530 5f 42 55 53 59 5d 0a 2a 2a 20 69 73 20 72 65 74  _BUSY].** is ret
1b540 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1b550 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
1b560 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
1b570 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1b580 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
1b590 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
1b5a0 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
1b5b0 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
1b5c0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
1b5d0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1b5e0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
1b5f0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
1b600 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1b610 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
1b620 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
1b630 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1b640 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1b650 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
1b660 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
1b670 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1b680 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1b690 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
1b6a0 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
1b6b0 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
1b6c0 6e 20 69 6e 76 6f 6b 65 64 20 70 72 65 76 69 6f  n invoked previo
1b6d0 75 73 6c 79 20 66 6f 72 20 74 68 65 20 73 61 6d  usly for the sam
1b6e0 65 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  e locking event.
1b6f0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
1b700 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
1b710 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
1b720 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
1b730 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
1b740 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1b750 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
1b760 5f 42 55 53 59 5d 20 69 73 20 72 65 74 75 72 6e  _BUSY] is return
1b770 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61 70 70  ed.** to the app
1b780 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66  lication..** ^If
1b790 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1b7a0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
1b7b0 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74  then another att
1b7c0 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20  empt.** is made 
1b7d0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61  to access the da
1b7e0 74 61 62 61 73 65 20 61 6e 64 20 74 68 65 20 63  tabase and the c
1b7f0 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a  ycle repeats..**
1b800 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65  .** The presence
1b810 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c   of a busy handl
1b820 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72  er does not guar
1b830 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69  antee that it wi
1b840 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a  ll be invoked.**
1b850 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c   when there is l
1b860 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20  ock contention. 
1b870 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72  ^If SQLite deter
1b880 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b  mines that invok
1b890 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20  ing the busy.** 
1b8a0 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65  handler could re
1b8b0 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f  sult in a deadlo
1b8c0 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61  ck, it will go a
1b8d0 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20  head and return 
1b8e0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a  [SQLITE_BUSY].**
1b8f0 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
1b900 69 6f 6e 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ion instead of i
1b910 6e 76 6f 6b 69 6e 67 20 74 68 65 20 0a 2a 2a 20  nvoking the .** 
1b920 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
1b930 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
1b940 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
1b950 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1b960 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
1b970 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
1b980 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
1b990 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
1b9a0 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
1b9b0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1b9c0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
1b9d0 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
1b9e0 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
1b9f0 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
1ba00 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
1ba10 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
1ba20 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
1ba30 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
1ba40 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
1ba50 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
1ba60 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
1ba70 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
1ba80 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
1ba90 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
1baa0 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
1bab0 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
1bac0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
1bad0 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
1bae0 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
1baf0 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
1bb00 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
1bb10 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
1bb20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
1bb30 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
1bb40 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
1bb50 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
1bb60 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
1bb70 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
1bb80 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
1bb90 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
1bba0 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
1bbb0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
1bbc0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
1bbd0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  LL..**.** ^(Ther
1bbe0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1bbf0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1bc00 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1bc10 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1bc20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1bc30 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1bc40 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1bc50 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1bc60 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1bc70 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1bc80 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1bc90 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1bca0 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e 67  ** or evaluating
1bcb0 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
1bcc0 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63 68  meout=N] will ch
1bcd0 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73 79  ange the.** busy
1bce0 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68 75   handler and thu
1bcf0 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65 76  s clear any prev
1bd00 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79 20  iously set busy 
1bd10 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
1bd20 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1bd30 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
1bd40 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
1bd50 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
1bd60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1bd70 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1bd80 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1bd90 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  er.  In other wo
1bda0 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73 79  rds,.** the busy
1bdb0 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74 20   handler is not 
1bdc0 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79 20  reentrant.  Any 
1bdd0 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20  such actions.** 
1bde0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
1bdf0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
1be00 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64   .** A busy hand
1be10 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ler must not clo
1be20 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1be30 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72  connection.** or
1be40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
1be50 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b  ment] that invok
1be60 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
1be70 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ler..*/.int sqli
1be80 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
1be90 28 73 71 6c 69 74 65 33 2a 2c 69 6e 74 28 2a 29  (sqlite3*,int(*)
1bea0 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 76 6f 69 64  (void*,int),void
1beb0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1bec0 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
1bed0 54 69 6d 65 6f 75 74 0a 2a 2a 20 4d 45 54 48 4f  Timeout.** METHO
1bee0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a  D: sqlite3.**.**
1bef0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
1bf00 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
1bf10 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
1bf20 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
1bf30 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
1bf40 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
1bf50 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
1bf60 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
1bf70 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
1bf80 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
1bf90 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
1bfa0 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
1bfb0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1bfc0 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
1bfd0 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
1bfe0 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
1bff0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
1c000 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
1c010 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
1c020 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
1c030 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
1c040 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
1c050 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
1c060 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1c070 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1c080 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
1c090 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
1c0a0 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
1c0b0 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
1c0c0 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
1c0d0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1c0e0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1c0f0 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
1c100 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1c110 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c120 6f 6e 5d 20 61 74 20 61 6e 79 20 67 69 76 65 6e  on] at any given
1c130 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f   moment.  If ano
1c140 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65  ther busy handle
1c150 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64  r.** was defined
1c160 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65    (using [sqlite
1c170 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1c180 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c  ]) prior to call
1c190 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  ing.** this rout
1c1a0 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20  ine, that other 
1c1b0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
1c1c0 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  cleared.)^.**.**
1c1d0 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 50 52 41   See also:  [PRA
1c1e0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
1c1f0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
1c200 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
1c210 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
1c220 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1c230 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
1c240 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
1c250 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 20 4d 45  ng Queries.** ME
1c260 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a  THOD: sqlite3.**
1c270 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
1c280 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
1c290 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
1c2a0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
1c2b0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1c2c0 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
1c2d0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
1c2e0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
1c2f0 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
1c300 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
1c310 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
1c320 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
1c330 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
1c340 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1c350 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
1c360 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
1c370 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
1c380 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
1c390 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
1c3a0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
1c3b0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
1c3c0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
1c3d0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
1c3e0 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
1c3f0 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
1c400 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
1c410 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1c420 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
1c430 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
1c440 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
1c450 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
1c460 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
1c470 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
1c480 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1c490 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
1c4a0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
1c4b0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
1c4c0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
1c4d0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
1c4e0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
1c4f0 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
1c500 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
1c510 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
1c520 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
1c530 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
1c540 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
1c550 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
1c560 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
1c570 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
1c580 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
1c590 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
1c5a0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
1c5b0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
1c5c0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
1c5d0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
1c5e0 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
1c5f0 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
1c600 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
1c610 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
1c620 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
1c630 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
1c640 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
1c650 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
1c660 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
1c670 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
1c680 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
1c690 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
1c6a0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
1c6b0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
1c6c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
1c6d0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
1c6e0 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
1c6f0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
1c700 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
1c710 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
1c720 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
1c730 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
1c740 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
1c750 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
1c760 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
1c770 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1c780 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1c790 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
1c7a0 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
1c7b0 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
1c7c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
1c7d0 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
1c7e0 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
1c7f0 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
1c800 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
1c810 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
1c820 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1c830 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
1c840 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
1c850 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
1c860 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
1c870 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
1c880 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
1c890 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
1c8a0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
1c8b0 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
1c8c0 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
1c8d0 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
1c8e0 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
1c8f0 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
1c900 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1c910 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
1c920 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
1c930 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
1c940 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1c950 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
1c960 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1c970 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
1c980 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1c990 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
1c9a0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1c9b0 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
1c9c0 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
1c9d0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
1c9e0 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
1c9f0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
1ca00 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
1ca10 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1ca20 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
1ca30 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ca40 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
1ca50 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1ca60 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
1ca70 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
1ca80 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
1ca90 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
1caa0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
1cab0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
1cac0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
1cad0 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
1cae0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
1caf0 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
1cb00 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
1cb10 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
1cb20 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
1cb30 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
1cb40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
1cb50 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
1cb60 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
1cb70 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1cb80 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
1cb90 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
1cba0 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
1cbb0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1cbc0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
1cbd0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
1cbe0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
1cbf0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
1cc00 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
1cc10 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
1cc20 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
1cc30 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
1cc40 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
1cc50 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
1cc60 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
1cc70 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
1cc80 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
1cc90 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
1cca0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1ccb0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
1ccc0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1ccd0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
1cce0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
1ccf0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1cd00 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
1cd10 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
1cd20 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
1cd30 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
1cd40 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
1cd50 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1cd60 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
1cd70 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
1cd80 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
1cd90 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
1cda0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
1cdb0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
1cdc0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
1cdd0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
1cde0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
1cdf0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
1ce00 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
1ce10 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
1ce20 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
1ce30 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
1ce40 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
1ce50 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
1ce60 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
1ce70 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
1ce80 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
1ce90 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
1cea0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
1ceb0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1cec0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1ced0 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1cee0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1cef0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1cf00 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1cf10 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1cf20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1cf30 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1cf40 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1cf50 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1cf60 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1cf70 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1cf80 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1cf90 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1cfa0 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1cfb0 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1cfc0 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1cfd0 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1cfe0 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1cff0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1d000 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76  ten here */.);.v
1d010 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1d020 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65  _table(char **re
1d030 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  sult);../*.** CA
1d040 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65  PI3REF: Formatte
1d050 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e  d String Printin
1d060 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1d070 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1d080 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73   are work-alikes
1d090 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28   of the "printf(
1d0a0 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e  )" family of fun
1d0b0 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74  ctions.** from t
1d0c0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1d0d0 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 73 65 20  brary..** These 
1d0e0 72 6f 75 74 69 6e 65 73 20 75 6e 64 65 72 73 74  routines underst
1d0f0 61 6e 64 20 6d 6f 73 74 20 6f 66 20 74 68 65 20  and most of the 
1d100 63 6f 6d 6d 6f 6e 20 4b 26 52 20 66 6f 72 6d 61  common K&R forma
1d110 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 2c 0a 2a  tting options,.*
1d120 2a 20 70 6c 75 73 20 73 6f 6d 65 20 61 64 64 69  * plus some addi
1d130 74 69 6f 6e 61 6c 20 6e 6f 6e 2d 73 74 61 6e 64  tional non-stand
1d140 61 72 64 20 66 6f 72 6d 61 74 73 2c 20 64 65 74  ard formats, det
1d150 61 69 6c 65 64 20 62 65 6c 6f 77 2e 0a 2a 2a 20  ailed below..** 
1d160 4e 6f 74 65 20 74 68 61 74 20 73 6f 6d 65 20 6f  Note that some o
1d170 66 20 74 68 65 20 6d 6f 72 65 20 6f 62 73 63 75  f the more obscu
1d180 72 65 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  re formatting op
1d190 74 69 6f 6e 73 20 66 72 6f 6d 20 72 65 63 65 6e  tions from recen
1d1a0 74 0a 2a 2a 20 43 2d 6c 69 62 72 61 72 79 20 73  t.** C-library s
1d1b0 74 61 6e 64 61 72 64 73 20 61 72 65 20 6f 6d 69  tandards are omi
1d1c0 74 74 65 64 20 66 72 6f 6d 20 74 68 69 73 20 69  tted from this i
1d1d0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a  mplementation..*
1d1e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d1f0 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1d200 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1d210 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1d220 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1d230 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1d240 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1d250 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1d260 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1d270 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1d280 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1d290 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1d2a0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1d2b0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1d2c0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1d2d0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1d2e0 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1d2f0 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1d300 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1d310 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1d320 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1d330 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1d340 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1d350 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1d360 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1d370 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1d380 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1d390 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1d3a0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1d3b0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1d3c0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1d3d0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1d3e0 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1d3f0 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1d400 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1d410 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1d420 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1d430 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1d440 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1d450 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1d460 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1d470 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1d480 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1d490 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1d4a0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1d4b0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1d4c0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1d4d0 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1d4e0 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1d4f0 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1d500 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1d510 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1d520 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1d530 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1d540 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1d550 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1d560 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1d570 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1d580 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1d590 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1d5a0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1d5b0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1d5c0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1d5d0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1d5e0 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1d5f0 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1d600 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1d610 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1d620 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1d630 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1d640 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1d650 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1d660 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1d670 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1d680 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1d690 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1d6a0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1d6b0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1d6c0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1d6d0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1d6e0 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1d6f0 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1d700 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1d710 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1d720 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1d730 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1d740 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1d750 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1d760 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1d770 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1d780 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1d790 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1d7a0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1d7b0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1d7c0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1d7d0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1d7e0 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1d7f0 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1d800 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1d810 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1d820 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1d830 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1d840 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1d850 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1d860 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1d870 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1d880 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1d890 22 25 77 22 20 61 6e 64 20 22 25 7a 22 20 6f 70  "%w" and "%z" op
1d8a0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tions..**.** ^(T
1d8b0 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72  he %q option wor
1d8c0 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68  ks like %s in th
1d8d0 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74 65  at it substitute
1d8e0 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  s a nul-terminat
1d8f0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f  ed.** string fro
1d900 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c  m the argument l
1d910 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73  ist.  But %q als
1d920 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20  o doubles every 
1d930 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a  '\'' character..
1d940 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e 65  ** %q is designe
1d950 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65  d for use inside
1d960 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
1d970 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e  l.)^  By doublin
1d980 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63  g each '\''.** c
1d990 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63 61  haracter it esca
1d9a0 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63 74  pes that charact
1d9b0 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74  er and allows it
1d9c0 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20   to be inserted 
1d9d0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69  into.** the stri
1d9e0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78  ng..**.** For ex
1d9f0 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68  ample, assume th
1da00 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c  e string variabl
1da10 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73  e zText contains
1da20 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73   text as follows
1da30 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1da40 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1da50 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27  ar *zText = "It'
1da60 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22 3b  s a happy day!";
1da70 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1da80 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e  kquote>.**.** On
1da90 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20 74  e can use this t
1daa0 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  ext in an SQL st
1dab0 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f  atement as follo
1dac0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1dad0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1dae0 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1daf0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1db00 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1db10 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a  VALUES('%q')", z
1db20 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1db30 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1db40 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1db50 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1db60 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1db70 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1db80 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71 20   Because the %q 
1db90 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73  format string is
1dba0 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20   used, the '\'' 
1dbb0 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65  character in zTe
1dbc0 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64  xt.** is escaped
1dbd0 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e   and the SQL gen
1dbe0 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c  erated is as fol
1dbf0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1dc00 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1dc10 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
1dc20 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
1dc30 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1dc40 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ).** </pre></blo
1dc50 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1dc60 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20  his is correct. 
1dc70 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73 20   Had we used %s 
1dc80 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74  instead of %q, t
1dc90 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c  he generated SQL
1dca0 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c  .** would have l
1dcb0 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a  ooked like this:
1dcc0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1dcd0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1dce0 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1dcf0 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20 68  VALUES('It's a h
1dd00 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20  appy day!');.** 
1dd10 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1dd20 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  te>.**.** This s
1dd30 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73  econd example is
1dd40 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65   an SQL syntax e
1dd50 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65  rror.  As a gene
1dd60 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f  ral rule you sho
1dd70 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73  uld.** always us
1dd80 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20  e %q instead of 
1dd90 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  %s when insertin
1dda0 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74  g text into a st
1ddb0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a  ring literal..**
1ddc0 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74  .** ^(The %Q opt
1ddd0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25  ion works like %
1dde0 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f  q except it also
1ddf0 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f   adds single quo
1de00 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68  tes around.** th
1de10 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  e outside of the
1de20 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20   total string.  
1de30 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66  Additionally, if
1de40 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1de50 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  n the.** argumen
1de60 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c  t list is a NULL
1de70 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62   pointer, %Q sub
1de80 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65 78  stitutes the tex
1de90 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75  t "NULL" (withou
1dea0 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74  t.** single quot
1deb0 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20  es).)^  So, for 
1dec0 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75  example, one cou
1ded0 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ld say:.**.** <b
1dee0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1def0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1df00 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1df10 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1df20 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c  ble VALUES(%Q)",
1df30 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1df40 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1df50 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1df60 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1df70 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1df80 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1df90 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76  ** The code abov
1dfa0 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20  e will render a 
1dfb0 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61 74  correct SQL stat
1dfc0 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51  ement in the zSQ
1dfd0 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76  L.** variable ev
1dfe0 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74 20  en if the zText 
1dff0 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
1e000 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1e010 2a 20 5e 28 54 68 65 20 22 25 77 22 20 66 6f 72  * ^(The "%w" for
1e020 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 69  matting option i
1e030 73 20 6c 69 6b 65 20 22 25 71 22 20 65 78 63 65  s like "%q" exce
1e040 70 74 20 74 68 61 74 20 69 74 20 65 78 70 65 63  pt that it expec
1e050 74 73 20 74 6f 0a 2a 2a 20 62 65 20 63 6f 6e 74  ts to.** be cont
1e060 61 69 6e 65 64 20 77 69 74 68 69 6e 20 64 6f 75  ained within dou
1e070 62 6c 65 2d 71 75 6f 74 65 73 20 69 6e 73 74 65  ble-quotes inste
1e080 61 64 20 6f 66 20 73 69 6e 67 6c 65 20 71 75 6f  ad of single quo
1e090 74 65 73 2c 20 61 6e 64 20 69 74 0a 2a 2a 20 65  tes, and it.** e
1e0a0 73 63 61 70 65 73 20 74 68 65 20 64 6f 75 62 6c  scapes the doubl
1e0b0 65 2d 71 75 6f 74 65 20 63 68 61 72 61 63 74 65  e-quote characte
1e0c0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1e0d0 20 73 69 6e 67 6c 65 2d 71 75 6f 74 65 0a 2a 2a   single-quote.**
1e0e0 20 63 68 61 72 61 63 74 65 72 2e 29 5e 20 20 54   character.)^  T
1e0f0 68 65 20 22 25 77 22 20 66 6f 72 6d 61 74 74 69  he "%w" formatti
1e100 6e 67 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 74  ng option is int
1e110 65 6e 64 65 64 20 66 6f 72 20 73 61 66 65 6c 79  ended for safely
1e120 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 61   inserting.** ta
1e130 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 6e  ble and column n
1e140 61 6d 65 73 20 69 6e 74 6f 20 61 20 63 6f 6e 73  ames into a cons
1e150 74 72 75 63 74 65 64 20 53 51 4c 20 73 74 61 74  tructed SQL stat
1e160 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ement..**.** ^(T
1e170 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1e180 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1e190 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1e1a0 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1e1b0 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1e1c0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1e1d0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1e1e0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1e1f0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1e200 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1e210 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1e220 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
1e230 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1e240 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1e250 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1e260 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1e270 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1e280 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1e290 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1e2a0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1e2b0 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1e2c0 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1e2d0 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1e2e0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1e2f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1e300 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1e310 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1e320 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1e330 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1e340 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1e350 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1e360 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1e370 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1e380 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1e390 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1e3a0 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1e3b0 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1e3c0 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1e3d0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1e3e0 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1e3f0 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1e400 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1e410 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1e420 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1e430 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e440 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1e450 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1e460 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1e470 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1e480 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1e490 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1e4a0 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1e4b0 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1e4c0 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1e4d0 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1e4e0 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1e4f0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1e500 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1e510 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1e520 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1e530 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1e540 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1e550 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1e560 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1e570 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1e580 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
1e590 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36 34  sqlite3_malloc64
1e5a0 28 4e 29 20 72 6f 75 74 69 6e 65 20 77 6f 72 6b  (N) routine work
1e5b0 73 20 6a 75 73 74 20 6c 69 6b 65 0a 2a 2a 20 73  s just like.** s
1e5c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1e5d0 20 65 78 63 65 70 74 20 74 68 61 74 20 4e 20 69   except that N i
1e5e0 73 20 61 6e 20 75 6e 73 69 67 6e 65 64 20 36 34  s an unsigned 64
1e5f0 2d 62 69 74 20 69 6e 74 65 67 65 72 20 69 6e 73  -bit integer ins
1e600 74 65 61 64 0a 2a 2a 20 6f 66 20 61 20 73 69 67  tead.** of a sig
1e610 6e 65 64 20 33 32 2d 62 69 74 20 69 6e 74 65 67  ned 32-bit integ
1e620 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1e630 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1e640 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1e650 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1e660 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1e670 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1e680 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1e690 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1e6a0 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1e6b0 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1e6c0 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1e6d0 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1e6e0 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1e6f0 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1e700 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1e710 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1e720 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1e730 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1e740 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1e750 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1e760 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1e770 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1e780 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1e790 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1e7a0 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1e7b0 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1e7c0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1e7d0 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1e7e0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1e7f0 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1e800 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1e810 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1e820 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1e830 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1e840 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1e850 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1e860 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1e870 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1e880 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1e890 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1e8a0 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1e8b0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1e8c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1e8d0 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29 20 69 6e  _realloc(X,N) in
1e8e0 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
1e8f0 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
1e900 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
1e910 6f 63 61 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  ocation X to be 
1e920 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1e930 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 58 20 70  ..** ^If the X p
1e940 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1e950 74 65 33 5f 72 65 61 6c 6c 6f 63 28 58 2c 4e 29  te3_realloc(X,N)
1e960 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1e970 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1e980 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1e990 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1e9a0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1e9b0 63 28 4e 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  c(N)..** ^If the
1e9c0 20 4e 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   N parameter to 
1e9d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1e9e0 58 2c 4e 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  X,N) is zero or.
1e9f0 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1ea00 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1ea10 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1ea20 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1ea30 73 71 6c 69 74 65 33 5f 66 72 65 65 28 58 29 2e  sqlite3_free(X).
1ea40 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1ea50 6c 6c 6f 63 28 58 2c 4e 29 20 72 65 74 75 72 6e  lloc(X,N) return
1ea60 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
1ea70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1ea80 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  on.** of at leas
1ea90 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  t N bytes in siz
1eaa0 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 69 6e 73  e or NULL if ins
1eab0 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79  ufficient memory
1eac0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
1ead0 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73  * ^If M is the s
1eae0 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72  ize of the prior
1eaf0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65   allocation, the
1eb00 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73  n min(N,M) bytes
1eb10 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72  .** of the prior
1eb20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20   allocation are 
1eb30 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20  copied into the 
1eb40 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66  beginning of buf
1eb50 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  fer returned.** 
1eb60 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  by sqlite3_reall
1eb70 6f 63 28 58 2c 4e 29 20 61 6e 64 20 74 68 65 20  oc(X,N) and the 
1eb80 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1eb90 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1eba0 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1ebb0 63 28 58 2c 4e 29 20 72 65 74 75 72 6e 73 20 4e  c(X,N) returns N
1ebc0 55 4c 4c 20 61 6e 64 20 4e 20 69 73 20 70 6f 73  ULL and N is pos
1ebd0 69 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 0a  itive, then the.
1ebe0 2a 2a 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  ** prior allocat
1ebf0 69 6f 6e 20 69 73 20 6e 6f 74 20 66 72 65 65 64  ion is not freed
1ec00 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1ec10 69 74 65 33 5f 72 65 61 6c 6c 6f 63 36 34 28 58  ite3_realloc64(X
1ec20 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 73 20 77  ,N) interfaces w
1ec30 6f 72 6b 73 20 74 68 65 20 73 61 6d 65 20 61 73  orks the same as
1ec40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  .** sqlite3_real
1ec50 6c 6f 63 28 58 2c 4e 29 20 65 78 63 65 70 74 20  loc(X,N) except 
1ec60 74 68 61 74 20 4e 20 69 73 20 61 20 36 34 2d 62  that N is a 64-b
1ec70 69 74 20 75 6e 73 69 67 6e 65 64 20 69 6e 74 65  it unsigned inte
1ec80 67 65 72 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ger instead.** o
1ec90 66 20 61 20 33 32 2d 62 69 74 20 73 69 67 6e 65  f a 32-bit signe
1eca0 64 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 0a 2a 2a  d integer..**.**
1ecb0 20 5e 49 66 20 58 20 69 73 20 61 20 6d 65 6d 6f   ^If X is a memo
1ecc0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 70 72  ry allocation pr
1ecd0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
1ece0 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1ecf0 61 6c 6c 6f 63 28 29 2c 0a 2a 2a 20 73 71 6c 69  alloc(),.** sqli
1ed00 74 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 29 2c 20  te3_malloc64(), 
1ed10 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1ed20 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ), or sqlite3_re
1ed30 61 6c 6c 6f 63 36 34 28 29 2c 20 74 68 65 6e 0a  alloc64(), then.
1ed40 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  ** sqlite3_msize
1ed50 28 58 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (X) returns the 
1ed60 73 69 7a 65 20 6f 66 20 74 68 61 74 20 6d 65 6d  size of that mem
1ed70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ory allocation i
1ed80 6e 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 54 68 65  n bytes..** ^The
1ed90 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
1eda0 62 79 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65  by sqlite3_msize
1edb0 28 58 29 20 6d 69 67 68 74 20 62 65 20 6c 61 72  (X) might be lar
1edc0 67 65 72 20 74 68 61 6e 20 74 68 65 20 6e 75 6d  ger than the num
1edd0 62 65 72 0a 2a 2a 20 6f 66 20 62 79 74 65 73 20  ber.** of bytes 
1ede0 72 65 71 75 65 73 74 65 64 20 77 68 65 6e 20 58  requested when X
1edf0 20 77 61 73 20 61 6c 6c 6f 63 61 74 65 64 2e 20   was allocated. 
1ee00 20 5e 49 66 20 58 20 69 73 20 61 20 4e 55 4c 4c   ^If X is a NULL
1ee10 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 0a 2a 2a   pointer then.**
1ee20 20 73 71 6c 69 74 65 33 5f 6d 73 69 7a 65 28 58   sqlite3_msize(X
1ee30 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 20  ) returns zero. 
1ee40 20 49 66 20 58 20 70 6f 69 6e 74 73 20 74 6f 20   If X points to 
1ee50 73 6f 6d 65 74 68 69 6e 67 20 74 68 61 74 20 69  something that i
1ee60 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 62 65 67  s not.** the beg
1ee70 69 6e 6e 69 6e 67 20 6f 66 20 6d 65 6d 6f 72 79  inning of memory
1ee80 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 6f 72 20   allocation, or 
1ee90 69 66 20 69 74 20 70 6f 69 6e 74 73 20 74 6f 20  if it points to 
1eea0 61 20 66 6f 72 6d 65 72 6c 79 0a 2a 2a 20 76 61  a formerly.** va
1eeb0 6c 69 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  lid memory alloc
1eec0 61 74 69 6f 6e 20 74 68 61 74 20 68 61 73 20 6e  ation that has n
1eed0 6f 77 20 62 65 65 6e 20 66 72 65 65 64 2c 20 74  ow been freed, t
1eee0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1eef0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6d  .** of sqlite3_m
1ef00 73 69 7a 65 28 58 29 20 69 73 20 75 6e 64 65 66  size(X) is undef
1ef10 69 6e 65 64 20 61 6e 64 20 70 6f 73 73 69 62 6c  ined and possibl
1ef20 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a  y harmful..**.**
1ef30 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1ef40 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1ef50 5f 6d 61 6c 6c 6f 63 28 29 2c 20 73 71 6c 69 74  _malloc(), sqlit
1ef60 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2c 0a 2a 2a  e3_realloc(),.**
1ef70 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 36   sqlite3_malloc6
1ef80 34 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  4(), and sqlite3
1ef90 5f 72 65 61 6c 6c 6f 63 36 34 28 29 0a 2a 2a 20  _realloc64().** 
1efa0 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65  is always aligne
1efb0 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e  d to at least an
1efc0 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8 byte boundary
1efd0 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62  , or to a.** 4 b
1efe0 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20  yte boundary if 
1eff0 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59  the [SQLITE_4_BY
1f000 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f  TE_ALIGNED_MALLO
1f010 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  C] compile-time.
1f020 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  ** option is use
1f030 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69  d..**.** In SQLi
1f040 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
1f050 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77   and 3.5.1, it w
1f060 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64  as possible to d
1f070 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c  efine.** the SQL
1f080 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f  ITE_OMIT_MEMORY_
1f090 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68  ALLOCATION which
1f0a0 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65   would cause the
1f0b0 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70   built-in.** imp
1f0c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
1f0d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  hese routines to
1f0e0 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68   be omitted.  Th
1f0f0 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  at capability.**
1f100 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72   is no longer pr
1f110 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75  ovided.  Only bu
1f120 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
1f130 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20  locators can be 
1f140 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f  used..**.** Prio
1f150 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73  r to SQLite vers
1f160 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20  ion 3.7.10, the 
1f170 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72  Windows OS inter
1f180 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65  face layer calle
1f190 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20  d.** the system 
1f1a0 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
1f1b0 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65  e() directly whe
1f1c0 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20  n converting.** 
1f1d0 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65  filenames betwee
1f1e0 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f  n the UTF-8 enco
1f1f0 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c  ding used by SQL
1f200 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65  ite.** and whate
1f210 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63  ver filename enc
1f220 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79  oding is used by
1f230 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
1f240 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61  Windows.** insta
1f250 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79  llation.  Memory
1f260 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
1f270 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64  rs were detected
1f280 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65  , but.** they we
1f290 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  re reported back
1f2a0 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54   as [SQLITE_CANT
1f2b0 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  OPEN] or.** [SQL
1f2c0 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65  ITE_IOERR] rathe
1f2d0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e  r than [SQLITE_N
1f2e0 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  OMEM]..**.** The
1f2f0 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
1f300 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ts to [sqlite3_f
1f310 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ree()] and [sqli
1f320 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a  te3_realloc()].*
1f330 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  * must be either
1f340 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f   NULL or else po
1f350 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20  inters obtained 
1f360 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20  from a prior.** 
1f370 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73  invocation of [s
1f380 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1f390 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61   or [sqlite3_rea
1f3a0 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76  lloc()] that hav
1f3b0 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65  e.** not yet bee
1f3c0 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a  n released..**.*
1f3d0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
1f3e0 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20  n must not read 
1f3f0 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72  or write any par
1f400 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20  t of.** a block 
1f410 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20  of memory after 
1f420 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65  it has been rele
1f430 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  ased using.** [s
1f440 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
1f450 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
1f460 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  oc()]..*/.void *
1f470 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
1f480 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74  nt);.void *sqlit
1f490 65 33 5f 6d 61 6c 6c 6f 63 36 34 28 73 71 6c 69  e3_malloc64(sqli
1f4a0 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a 76 6f 69  te3_uint64);.voi
1f4b0 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d *sqlite3_reall
1f4c0 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  oc(void*, int);.
1f4d0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1f4e0 61 6c 6c 6f 63 36 34 28 76 6f 69 64 2a 2c 20 73  alloc64(void*, s
1f4f0 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 3b 0a  qlite3_uint64);.
1f500 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1f510 65 28 76 6f 69 64 2a 29 3b 0a 73 71 6c 69 74 65  e(void*);.sqlite
1f520 33 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  3_uint64 sqlite3
1f530 5f 6d 73 69 7a 65 28 76 6f 69 64 2a 29 3b 0a 0a  _msize(void*);..
1f540 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1f550 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1f560 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1f570 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1f580 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1f590 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1f5a0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1f5b0 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1f5c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1f5d0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f5e0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1f5f0 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1f600 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1f610 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1f620 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1f630 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1f640 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1f650 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1f660 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1f670 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1f680 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1f690 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1f6a0 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1f6b0 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1f6c0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1f6d0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1f6e0 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1f6f0 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1f700 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1f710 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1f720 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1f730 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1f740 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1f750 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1f760 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1f770 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1f780 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1f790 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1f7a0 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1f7b0 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1f7c0 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1f7d0 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1f7e0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1f7f0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1f800 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1f810 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1f820 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1f830 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1f840 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1f850 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1f860 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1f870 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1f880 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1f890 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1f8a0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1f8b0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1f8c0 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1f8d0 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1f8e0 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1f8f0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1f900 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1f910 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1f920 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1f930 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1f940 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1f950 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1f960 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1f970 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
1f980 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1f990 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1f9a0 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
1f9b0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1f9c0 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1f9d0 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1f9e0 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1f9f0 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1fa00 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1fa10 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1fa20 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1fa30 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
1fa40 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
1fa50 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
1fa60 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
1fa70 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
1fa80 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
1fa90 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
1faa0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
1fab0 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
1fac0 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
1fad0 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
1fae0 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
1faf0 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
1fb00 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
1fb10 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
1fb20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
1fb30 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1fb40 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
1fb50 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
1fb60 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
1fb70 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
1fb80 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
1fb90 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1fba0 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
1fbb0 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
1fbc0 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e  o buffer P..** ^
1fbd0 54 68 65 20 50 20 70 61 72 61 6d 65 74 65 72 20  The P parameter 
1fbe0 63 61 6e 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  can be a NULL po
1fbf0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  inter..**.** ^If
1fc00 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 68 61   this routine ha
1fc10 73 20 6e 6f 74 20 62 65 65 6e 20 70 72 65 76 69  s not been previ
1fc20 6f 75 73 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20  ously called or 
1fc30 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 0a  if the previous.
1fc40 2a 2a 20 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65  ** call had N le
1fc50 73 73 20 74 68 61 6e 20 6f 6e 65 20 6f 72 20 61  ss than one or a
1fc60 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
1fc70 72 20 50 2c 20 74 68 65 6e 20 74 68 65 20 50 52  r P, then the PR
1fc80 4e 47 20 69 73 0a 2a 2a 20 73 65 65 64 65 64 20  NG is.** seeded 
1fc90 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1fca0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 74   obtained from t
1fcb0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1fcc0 65 74 68 6f 64 20 6f 66 0a 2a 2a 20 74 68 65 20  ethod of.** the 
1fcd0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1fce0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1fcf0 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
1fd00 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
1fd10 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
1fd20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 61 6e 64  of 1 or more and
1fd30 20 61 0a 2a 2a 20 6e 6f 6e 2d 4e 55 4c 4c 20 50   a.** non-NULL P
1fd40 20 74 68 65 6e 20 74 68 65 20 70 73 65 75 64 6f   then the pseudo
1fd50 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1fd60 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1fd70 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1fd80 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1fd90 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1fda0 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1fdb0 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20  method..*/.void 
1fdc0 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
1fdd0 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
1fde0 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
1fdf0 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1fe00 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
1fe10 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54  Callbacks.** MET
1fe20 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a  HOD: sqlite3.**.
1fe30 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1fe40 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
1fe50 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1fe60 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
1fe70 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1fe80 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
1fe90 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
1fea0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
1feb0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1fec0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1fed0 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
1fee0 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
1fef0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
1ff00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1ff10 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1ff20 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
1ff30 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
1ff40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1ff50 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
1ff60 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1ff70 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
1ff80 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
1ff90 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
1ffa0 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
1ffb0 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
1ffc0 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
1ffd0 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
1ffe0 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
1fff0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
20000 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
20010 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
20020 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
20030 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
20040 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
20050 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
20060 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
20070 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
20080 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
20090 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
200a0 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
200b0 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
200c0 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
200d0 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
200e0 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
200f0 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
20100 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
20110 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
20120 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
20130 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
20140 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
20150 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20160 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
20170 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
20180 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
20190 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
201a0 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
201b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
201c0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
201d0 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
201e0 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
201f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
20200 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
20210 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
20220 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
20230 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
20240 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
20250 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
20260 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
20270 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
20280 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
20290 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
202a0 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
202b0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
202c0 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
202d0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
202e0 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
202f0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
20300 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
20310 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
20320 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
20330 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
20340 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
20350 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
20360 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20370 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
20380 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
20390 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
203a0 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
203b0 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
203c0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
203d0 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
203e0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
203f0 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
20400 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
20410 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
20420 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
20430 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
20440 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
20450 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
20460 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
20470 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
20480 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
20490 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
204a0 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
204b0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
204c0 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
204d0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
204e0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
204f0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
20500 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
20510 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
20520 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
20530 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
20540 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
20550 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
20560 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
20570 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
20580 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
20590 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
205a0 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
205b0 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
205c0 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
205d0 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
205e0 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
205f0 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
20600 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
20610 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
20620 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
20630 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
20640 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
20650 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
20660 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
20670 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
20680 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
20690 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
206a0 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
206b0 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
206c0 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
206d0 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
206e0 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
206f0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
20700 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
20710 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
20720 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
20730 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
20740 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
20750 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
20760 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
20770 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
20780 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
20790 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
207a0 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
207b0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
207c0 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
207d0 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
207e0 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
207f0 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
20800 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
20810 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
20820 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
20830 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
20840 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
20850 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
20860 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
20870 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
20880 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
20890 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
208a0 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
208b0 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
208c0 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
208d0 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
208e0 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
208f0 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
20900 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
20910 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
20920 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
20930 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
20940 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
20950 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
20960 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
20970 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
20980 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
20990 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
209a0 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
209b0 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
209c0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
209d0 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
209e0 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
209f0 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
20a00 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
20a10 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
20a20 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
20a30 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
20a40 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
20a50 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
20a60 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
20a70 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
20a80 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
20a90 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
20aa0 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
20ab0 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
20ac0 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
20ad0 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
20ae0 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
20af0 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
20b00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
20b10 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
20b20 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
20b30 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
20b40 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
20b50 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
20b60 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
20b70 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
20b80 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
20b90 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
20ba0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
20bb0 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
20bc0 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
20bd0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20be0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
20bf0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
20c00 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
20c10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20c20 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
20c30 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
20c40 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
20c50 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
20c60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
20c70 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
20c80 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
20c90 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
20ca0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
20cb0 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
20cc0 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
20cd0 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
20ce0 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
20cf0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
20d00 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
20d10 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
20d20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
20d30 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
20d40 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
20d50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
20d60 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
20d70 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
20d80 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
20d90 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
20da0 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
20db0 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
20dc0 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
20dd0 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
20de0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
20df0 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
20e00 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
20e10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
20e20 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
20e30 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
20e40 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
20e50 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
20e60 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
20e70 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
20e80 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
20e90 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
20ea0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20eb0 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
20ec0 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
20ed0 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
20ee0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
20ef0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
20f00 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
20f10 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
20f20 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
20f30 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
20f40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
20f50 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
20f60 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
20f70 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
20f80 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
20f90 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
20fa0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
20fb0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
20fc0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
20fd0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
20fe0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
20ff0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
21000 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
21010 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
21020 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
21030 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
21040 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
21050 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
21060 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
21070 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
21080 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
21090 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
210a0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
210b0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
210c0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
210d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
210e0 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
210f0 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
21100 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
21110 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
21120 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
21130 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
21140 75 73 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c  used as a [confl
21150 69 63 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d  ict resolution m
21160 6f 64 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64  ode].** returned
21170 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
21180 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
21190 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ict()] interface
211a0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
211b0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
211c0 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
211d0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
211e0 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
211f0 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
21200 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
21210 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
21220 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
21230 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
21240 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
21250 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
21260 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
21270 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
21280 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
21290 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
212a0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
212b0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
212c0 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
212d0 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
212e0 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
212f0 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
21300 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
21310 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
21320 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
21330 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
21340 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
21350 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
21360 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
21370 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
21380 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
21390 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
213a0 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
213b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
213c0 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
213d0 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
213e0 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
213f0 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
21400 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
21410 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
21420 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
21430 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
21440 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
21450 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
21460 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
21470 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
21480 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
21490 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
214a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
214b0 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
214c0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
214d0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
214e0 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
214f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
21500 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
21510 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
21520 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
21530 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
21540 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
21550 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
21560 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
21570 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
21580 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
21590 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
215a0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
215b0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
215c0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
215d0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
215e0 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
215f0 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
21600 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
21610 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21620 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
21630 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
21640 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
21650 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21660 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
21670 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
21680 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
21690 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
216a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
216b0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
216c0 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
216d0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
216e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
216f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21700 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
21710 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
21720 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
21730 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21740 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21750 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
21760 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
21770 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21780 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21790 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
217a0 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
217b0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
217c0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
217d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
217e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
217f0 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
21800 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
21810 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21820 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21830 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
21840 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
21850 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
21860 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
21870 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21880 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
21890 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
218a0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
218b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
218c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
218d0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
218e0 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
218f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21900 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21910 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21920 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
21930 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
21940 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
21950 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21960 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21970 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
21980 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
21990 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
219a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
219b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
219c0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
219d0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
219e0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
219f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21a00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21a10 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
21a20 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
21a30 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21a40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21a50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21a60 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
21a70 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
21a80 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
21a90 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
21aa0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21ab0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
21ac0 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
21ad0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
21ae0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21af0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21b00 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
21b10 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
21b20 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
21b30 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21b40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21b50 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
21b60 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
21b70 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
21b80 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21b90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
21ba0 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
21bb0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
21bc0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
21bd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21be0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
21bf0 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
21c00 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
21c10 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
21c20 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
21c30 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
21c40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21c50 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
21c60 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
21c70 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
21c80 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
21c90 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
21ca0 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
21cb0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
21cc0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21cd0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
21ce0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
21cf0 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
21d00 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21d10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21d20 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
21d30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
21d40 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21d50 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
21d60 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
21d70 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
21d80 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
21d90 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
21da0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21db0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21dc0 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
21dd0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
21de0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
21df0 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
21e00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21e10 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
21e20 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
21e30 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
21e40 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21e50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21e60 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
21e70 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
21e80 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
21e90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21ea0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21eb0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
21ec0 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
21ed0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21ee0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21ef0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21f00 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
21f10 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
21f20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21f30 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
21f40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21f50 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
21f60 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
21f70 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
21f80 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
21f90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21fa0 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
21fb0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
21fc0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
21fd0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
21fe0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21ff0 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
22000 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
22010 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
22020 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
22030 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22040 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
22050 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
22060 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64  onger used */.#d
22070 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43  efine SQLITE_REC
22080 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20 20  URSIVE          
22090 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    33   /* NULL  
220a0 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20            NULL  
220b0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a            */../*
220c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
220d0 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
220e0 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
220f0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
22100 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
22110 74 69 6e 65 73 20 61 72 65 20 64 65 70 72 65 63  tines are deprec
22120 61 74 65 64 2e 20 55 73 65 20 74 68 65 20 5b 73  ated. Use the [s
22130 71 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28  qlite3_trace_v2(
22140 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
22150 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 72  instead of the r
22160 6f 75 74 69 6e 65 73 20 64 65 73 63 72 69 62 65  outines describe
22170 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  d here..**.** Th
22180 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
22190 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
221a0 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
221b0 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
221c0 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
221d0 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
221e0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
221f0 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
22200 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
22210 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
22220 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
22230 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
22240 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
22250 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
22260 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
22270 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
22280 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
22290 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
222a0 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
222b0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
222c0 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
222d0 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
222e0 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
222f0 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
22300 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
22310 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
22320 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
22330 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
22340 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
22350 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
22360 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
22370 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
22380 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
22390 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
223a0 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
223b0 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
223c0 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
223d0 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
223e0 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49 4d 49  _TRACE_SIZE_LIMI
223f0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
22400 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
22410 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a 20 74  ed to limit.** t
22420 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b 62 6f  he length of [bo
22430 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d 20 65  und parameter] e
22440 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68 65 20  xpansion in the 
22450 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69 74 65  output of sqlite
22460 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a 2a 2a  3_trace()..**.**
22470 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
22480 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
22490 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72  ed by sqlite3_pr
224a0 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b  ofile() is invok
224b0 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51  ed.** as each SQ
224c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69  L statement fini
224d0 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66  shes.  ^The prof
224e0 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  ile callback con
224f0 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69  tains.** the ori
22500 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20  ginal statement 
22510 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69  text and an esti
22520 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f  mate of wall-clo
22530 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f  ck time.** of ho
22540 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74  w long that stat
22550 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75  ement took to ru
22560 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65  n.  ^The profile
22570 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d   callback.** tim
22580 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66  e is in units of
22590 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f   nanoseconds, ho
225a0 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e  wever the curren
225b0 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
225c0 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61  .** is only capa
225d0 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ble of milliseco
225e0 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f  nd resolution so
225f0 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73   the six least s
22600 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69  ignificant.** di
22610 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65  gits in the time
22620 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73   are meaningless
22630 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
22640 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  ns of SQLite.** 
22650 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72  might provide gr
22660 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e  eater resolution
22670 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72   on the profiler
22680 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a   callback.  The.
22690 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69  ** sqlite3_profi
226a0 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  le() function is
226b0 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65   considered expe
226c0 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a  rimental and is.
226d0 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68  ** subject to ch
226e0 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76  ange in future v
226f0 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
22700 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50  e..*/.SQLITE_DEP
22710 52 45 43 41 54 45 44 20 76 6f 69 64 20 2a 73 71  RECATED void *sq
22720 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
22730 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
22740 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  Trace)(void*,con
22750 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a  st char*), void*
22760 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
22770 41 54 45 44 20 76 6f 69 64 20 2a 73 71 6c 69 74  ATED void *sqlit
22780 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
22790 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
227a0 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
227b0 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
227c0 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
227d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
227e0 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 45 76  EF: SQL Trace Ev
227f0 65 6e 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ent Codes.** KEY
22800 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 52  WORDS: SQLITE_TR
22810 41 43 45 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ACE.**.** These 
22820 63 6f 6e 73 74 61 6e 74 73 20 69 64 65 6e 74 69  constants identi
22830 66 79 20 63 6c 61 73 73 65 73 20 6f 66 20 65 76  fy classes of ev
22840 65 6e 74 73 20 74 68 61 74 20 63 61 6e 20 62 65  ents that can be
22850 20 6d 6f 6e 69 74 6f 72 65 64 0a 2a 2a 20 75 73   monitored.** us
22860 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ing the [sqlite3
22870 5f 74 72 61 63 65 5f 76 32 28 29 5d 20 74 72 61  _trace_v2()] tra
22880 63 69 6e 67 20 6c 6f 67 69 63 2e 20 20 54 68 65  cing logic.  The
22890 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
228a0 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74  ** to [sqlite3_t
228b0 72 61 63 65 5f 76 32 28 29 5d 20 69 73 20 61 6e  race_v2()] is an
228c0 20 4f 52 2d 65 64 20 63 6f 6d 62 69 6e 61 74 69   OR-ed combinati
228d0 6f 6e 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72  on of one or mor
228e0 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c  e of.** the foll
228f0 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 2e  owing constants.
22900 20 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67    ^The first arg
22910 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 74 72 61  ument to the tra
22920 63 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  ce callback.** i
22930 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  s one of the fol
22940 6c 6f 77 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73  lowing constants
22950 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 74 72 61 63  ..**.** New trac
22960 69 6e 67 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ing constants ma
22970 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
22980 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a  ture releases..*
22990 2a 0a 2a 2a 20 5e 41 20 74 72 61 63 65 20 63 61  *.** ^A trace ca
229a0 6c 6c 62 61 63 6b 20 68 61 73 20 66 6f 75 72 20  llback has four 
229b0 61 72 67 75 6d 65 6e 74 73 3a 20 78 43 61 6c 6c  arguments: xCall
229c0 62 61 63 6b 28 54 2c 43 2c 50 2c 58 29 2e 0a 2a  back(T,C,P,X)..*
229d0 2a 20 5e 54 68 65 20 54 20 61 72 67 75 6d 65 6e  * ^The T argumen
229e0 74 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20  t is one of the 
229f0 69 6e 74 65 67 65 72 20 74 79 70 65 20 63 6f 64  integer type cod
22a00 65 73 20 61 62 6f 76 65 2e 0a 2a 2a 20 5e 54 68  es above..** ^Th
22a10 65 20 43 20 61 72 67 75 6d 65 6e 74 20 69 73 20  e C argument is 
22a20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  a copy of the co
22a30 6e 74 65 78 74 20 70 6f 69 6e 74 65 72 20 70 61  ntext pointer pa
22a40 73 73 65 64 20 69 6e 20 61 73 20 74 68 65 0a 2a  ssed in as the.*
22a50 2a 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  * fourth argumen
22a60 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 74 72  t to [sqlite3_tr
22a70 61 63 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 54 68  ace_v2()]..** Th
22a80 65 20 50 20 61 6e 64 20 58 20 61 72 67 75 6d 65  e P and X argume
22a90 6e 74 73 20 61 72 65 20 70 6f 69 6e 74 65 72 73  nts are pointers
22aa0 20 77 68 6f 73 65 20 6d 65 61 6e 69 6e 67 73 20   whose meanings 
22ab0 64 65 70 65 6e 64 20 6f 6e 20 54 2e 0a 2a 2a 0a  depend on T..**.
22ac0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
22ad0 49 54 45 5f 54 52 41 43 45 5f 53 54 4d 54 5d 5d  ITE_TRACE_STMT]]
22ae0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41 43   <dt>SQLITE_TRAC
22af0 45 5f 53 54 4d 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  E_STMT</dt>.** <
22b00 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
22b10 41 43 45 5f 53 54 4d 54 20 63 61 6c 6c 62 61 63  ACE_STMT callbac
22b20 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  k is invoked whe
22b30 6e 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  n a prepared sta
22b40 74 65 6d 65 6e 74 0a 2a 2a 20 66 69 72 73 74 20  tement.** first 
22b50 62 65 67 69 6e 73 20 72 75 6e 6e 69 6e 67 20 61  begins running a
22b60 6e 64 20 70 6f 73 73 69 62 6c 79 20 61 74 20 6f  nd possibly at o
22b70 74 68 65 72 20 74 69 6d 65 73 20 64 75 72 69 6e  ther times durin
22b80 67 20 74 68 65 0a 2a 2a 20 65 78 65 63 75 74 69  g the.** executi
22b90 6f 6e 20 6f 66 20 74 68 65 20 70 72 65 70 61 72  on of the prepar
22ba0 65 64 20 73 74 61 74 65 6d 65 6e 74 2c 20 73 75  ed statement, su
22bb0 63 68 20 61 73 20 61 74 20 74 68 65 20 73 74 61  ch as at the sta
22bc0 72 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 74 72  rt of each.** tr
22bd0 69 67 67 65 72 20 73 75 62 70 72 6f 67 72 61 6d  igger subprogram
22be0 2e 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  . ^The P argumen
22bf0 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
22c00 6f 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  o the.** [prepar
22c10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
22c20 54 68 65 20 58 20 61 72 67 75 6d 65 6e 74 20 69  The X argument i
22c30 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
22c40 20 73 74 72 69 6e 67 20 77 68 69 63 68 0a 2a 2a   string which.**
22c50 20 69 73 20 74 68 65 20 75 6e 65 78 70 61 6e 64   is the unexpand
22c60 65 64 20 53 51 4c 20 74 65 78 74 20 6f 66 20 74  ed SQL text of t
22c70 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
22c80 65 6d 65 6e 74 20 6f 72 20 61 6e 20 53 51 4c 20  ement or an SQL 
22c90 63 6f 6d 6d 65 6e 74 20 0a 2a 2a 20 74 68 61 74  comment .** that
22ca0 20 69 6e 64 69 63 61 74 65 73 20 74 68 65 20 69   indicates the i
22cb0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 61 20 74  nvocation of a t
22cc0 72 69 67 67 65 72 2e 20 20 5e 54 68 65 20 63 61  rigger.  ^The ca
22cd0 6c 6c 62 61 63 6b 20 63 61 6e 20 63 6f 6d 70 75  llback can compu
22ce0 74 65 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 74  te.** the same t
22cf0 65 78 74 20 74 68 61 74 20 77 6f 75 6c 64 20 68  ext that would h
22d00 61 76 65 20 62 65 65 6e 20 72 65 74 75 72 6e 65  ave been returne
22d10 64 20 62 79 20 74 68 65 20 6c 65 67 61 63 79 20  d by the legacy 
22d20 5b 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29  [sqlite3_trace()
22d30 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 62  ].** interface b
22d40 79 20 75 73 69 6e 67 20 74 68 65 20 58 20 61 72  y using the X ar
22d50 67 75 6d 65 6e 74 20 77 68 65 6e 20 58 20 62 65  gument when X be
22d60 67 69 6e 73 20 77 69 74 68 20 22 2d 2d 22 20 61  gins with "--" a
22d70 6e 64 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 5b  nd invoking.** [
22d80 73 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64  sqlite3_expanded
22d90 5f 73 71 6c 28 50 29 5d 20 6f 74 68 65 72 77 69  _sql(P)] otherwi
22da0 73 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  se..**.** [[SQLI
22db0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
22dc0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52  ]] <dt>SQLITE_TR
22dd0 41 43 45 5f 50 52 4f 46 49 4c 45 3c 2f 64 74 3e  ACE_PROFILE</dt>
22de0 0a 2a 2a 20 3c 64 64 3e 5e 41 6e 20 53 51 4c 49  .** <dd>^An SQLI
22df0 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c 45  TE_TRACE_PROFILE
22e00 20 63 61 6c 6c 62 61 63 6b 20 70 72 6f 76 69 64   callback provid
22e10 65 73 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  es approximately
22e20 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 69 6e 66   the same.** inf
22e30 6f 72 6d 61 74 69 6f 6e 20 61 73 20 69 73 20 70  ormation as is p
22e40 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 5b  rovided by the [
22e50 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
22e60 29 5d 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  )] callback..** 
22e70 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20  ^The P argument 
22e80 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
22e90 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
22ea0 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 74 68 65  atement] and the
22eb0 0a 2a 2a 20 58 20 61 72 67 75 6d 65 6e 74 20 70  .** X argument p
22ec0 6f 69 6e 74 73 20 74 6f 20 61 20 36 34 2d 62 69  oints to a 64-bi
22ed0 74 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  t integer which 
22ee0 69 73 20 74 68 65 20 65 73 74 69 6d 61 74 65 64  is the estimated
22ef0 20 6f 66 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65   of.** the numbe
22f00 72 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 20  r of nanosecond 
22f10 74 68 61 74 20 74 68 65 20 70 72 65 70 61 72 65  that the prepare
22f20 64 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  d statement took
22f30 20 74 6f 20 72 75 6e 2e 0a 2a 2a 20 5e 54 68 65   to run..** ^The
22f40 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 50 52   SQLITE_TRACE_PR
22f50 4f 46 49 4c 45 20 63 61 6c 6c 62 61 63 6b 20 69  OFILE callback i
22f60 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74  s invoked when t
22f70 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  he statement fin
22f80 69 73 68 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ishes..**.** [[S
22f90 51 4c 49 54 45 5f 54 52 41 43 45 5f 52 4f 57 5d  QLITE_TRACE_ROW]
22fa0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 54 52 41  ] <dt>SQLITE_TRA
22fb0 43 45 5f 52 4f 57 3c 2f 64 74 3e 0a 2a 2a 20 3c  CE_ROW</dt>.** <
22fc0 64 64 3e 5e 41 6e 20 53 51 4c 49 54 45 5f 54 52  dd>^An SQLITE_TR
22fd0 41 43 45 5f 52 4f 57 20 63 61 6c 6c 62 61 63 6b  ACE_ROW callback
22fe0 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
22ff0 65 76 65 72 20 61 20 70 72 65 70 61 72 65 64 0a  ever a prepared.
23000 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 67 65 6e  ** statement gen
23010 65 72 61 74 65 73 20 61 20 73 69 6e 67 6c 65 20  erates a single 
23020 72 6f 77 20 6f 66 20 72 65 73 75 6c 74 2e 20 20  row of result.  
23030 0a 2a 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d  .** ^The P argum
23040 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
23050 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
23060 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64  d statement] and
23070 20 74 68 65 0a 2a 2a 20 58 20 61 72 67 75 6d 65   the.** X argume
23080 6e 74 20 69 73 20 75 6e 75 73 65 64 2e 0a 2a 2a  nt is unused..**
23090 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 54 52 41  .** [[SQLITE_TRA
230a0 43 45 5f 43 4c 4f 53 45 5d 5d 20 3c 64 74 3e 53  CE_CLOSE]] <dt>S
230b0 51 4c 49 54 45 5f 54 52 41 43 45 5f 43 4c 4f 53  QLITE_TRACE_CLOS
230c0 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 5e 41  E</dt>.** <dd>^A
230d0 6e 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 43  n SQLITE_TRACE_C
230e0 4c 4f 53 45 20 63 61 6c 6c 62 61 63 6b 20 69 73  LOSE callback is
230f0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 61 20   invoked when a 
23100 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
23110 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 0a 2a  ection closes..*
23120 2a 20 5e 54 68 65 20 50 20 61 72 67 75 6d 65 6e  * ^The P argumen
23130 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
23140 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  o the [database 
23150 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65  connection] obje
23160 63 74 0a 2a 2a 20 61 6e 64 20 74 68 65 20 58 20  ct.** and the X 
23170 61 72 67 75 6d 65 6e 74 20 69 73 20 75 6e 75 73  argument is unus
23180 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  ed..** </dl>.*/.
23190 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
231a0 52 41 43 45 5f 53 54 4d 54 20 20 20 20 20 20 20  RACE_STMT       
231b0 30 78 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0x01.#define SQL
231c0 49 54 45 5f 54 52 41 43 45 5f 50 52 4f 46 49 4c  ITE_TRACE_PROFIL
231d0 45 20 20 20 20 30 78 30 32 0a 23 64 65 66 69 6e  E    0x02.#defin
231e0 65 20 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 52  e SQLITE_TRACE_R
231f0 4f 57 20 20 20 20 20 20 20 20 30 78 30 34 0a 23  OW        0x04.#
23200 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
23210 41 43 45 5f 43 4c 4f 53 45 20 20 20 20 20 20 30  ACE_CLOSE      0
23220 78 30 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  x08../*.** CAPI3
23230 52 45 46 3a 20 53 51 4c 20 54 72 61 63 65 20 48  REF: SQL Trace H
23240 6f 6f 6b 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ook.** METHOD: s
23250 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54 68  qlite3.**.** ^Th
23260 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 5f  e sqlite3_trace_
23270 76 32 28 44 2c 4d 2c 58 2c 50 29 20 69 6e 74 65  v2(D,M,X,P) inte
23280 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
23290 61 20 74 72 61 63 65 20 63 61 6c 6c 62 61 63 6b  a trace callback
232a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 61  .** function X a
232b0 67 61 69 6e 73 74 20 5b 64 61 74 61 62 61 73 65  gainst [database
232c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20   connection] D, 
232d0 75 73 69 6e 67 20 70 72 6f 70 65 72 74 79 20 6d  using property m
232e0 61 73 6b 20 4d 0a 2a 2a 20 61 6e 64 20 63 6f 6e  ask M.** and con
232f0 74 65 78 74 20 70 6f 69 6e 74 65 72 20 50 2e 20  text pointer P. 
23300 20 5e 49 66 20 74 68 65 20 58 20 63 61 6c 6c 62   ^If the X callb
23310 61 63 6b 20 69 73 0a 2a 2a 20 4e 55 4c 4c 20 6f  ack is.** NULL o
23320 72 20 69 66 20 74 68 65 20 4d 20 6d 61 73 6b 20  r if the M mask 
23330 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72  is zero, then tr
23340 61 63 69 6e 67 20 69 73 20 64 69 73 61 62 6c 65  acing is disable
23350 64 2e 20 20 54 68 65 0a 2a 2a 20 4d 20 61 72 67  d.  The.** M arg
23360 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
23370 74 68 65 20 62 69 74 77 69 73 65 20 4f 52 2d 65  the bitwise OR-e
23380 64 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  d combination of
23390 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  .** zero or more
233a0 20 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5d 20   [SQLITE_TRACE] 
233b0 63 6f 6e 73 74 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a  constants..**.**
233c0 20 5e 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 65   ^Each call to e
233d0 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 74 72  ither sqlite3_tr
233e0 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ace() or sqlite3
233f0 5f 74 72 61 63 65 5f 76 32 28 29 20 6f 76 65 72  _trace_v2() over
23400 72 69 64 65 73 20 0a 2a 2a 20 28 63 61 6e 63 65  rides .** (cance
23410 6c 73 29 20 61 6e 79 20 70 72 69 6f 72 20 63 61  ls) any prior ca
23420 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 74  lls to sqlite3_t
23430 72 61 63 65 28 29 20 6f 72 20 73 71 6c 69 74 65  race() or sqlite
23440 33 5f 74 72 61 63 65 5f 76 32 28 29 2e 0a 2a 2a  3_trace_v2()..**
23450 0a 2a 2a 20 5e 54 68 65 20 58 20 63 61 6c 6c 62  .** ^The X callb
23460 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
23470 68 65 6e 65 76 65 72 20 61 6e 79 20 6f 66 20 74  henever any of t
23480 68 65 20 65 76 65 6e 74 73 20 69 64 65 6e 74 69  he events identi
23490 66 69 65 64 20 62 79 20 0a 2a 2a 20 6d 61 73 6b  fied by .** mask
234a0 20 4d 20 6f 63 63 75 72 2e 20 20 5e 54 68 65 20   M occur.  ^The 
234b0 69 6e 74 65 67 65 72 20 72 65 74 75 72 6e 20 76  integer return v
234c0 61 6c 75 65 20 66 72 6f 6d 20 74 68 65 20 63 61  alue from the ca
234d0 6c 6c 62 61 63 6b 20 69 73 20 63 75 72 72 65 6e  llback is curren
234e0 74 6c 79 0a 2a 2a 20 69 67 6e 6f 72 65 64 2c 20  tly.** ignored, 
234f0 74 68 6f 75 67 68 20 74 68 69 73 20 6d 61 79 20  though this may 
23500 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
23510 20 72 65 6c 65 61 73 65 73 2e 20 20 43 61 6c 6c   releases.  Call
23520 62 61 63 6b 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  back.** implemen
23530 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 72  tations should r
23540 65 74 75 72 6e 20 7a 65 72 6f 20 74 6f 20 65 6e  eturn zero to en
23550 73 75 72 65 20 66 75 74 75 72 65 20 63 6f 6d 70  sure future comp
23560 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
23570 20 5e 41 20 74 72 61 63 65 20 63 61 6c 6c 62 61   ^A trace callba
23580 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
23590 74 68 20 66 6f 75 72 20 61 72 67 75 6d 65 6e 74  th four argument
235a0 73 3a 20 63 61 6c 6c 62 61 63 6b 28 54 2c 43 2c  s: callback(T,C,
235b0 50 2c 58 29 2e 0a 2a 2a 20 5e 54 68 65 20 54 20  P,X)..** ^The T 
235c0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
235d0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
235e0 52 41 43 45 5d 0a 2a 2a 20 63 6f 6e 73 74 61 6e  RACE].** constan
235f0 74 73 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77  ts to indicate w
23600 68 79 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  hy the callback 
23610 77 61 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20  was invoked..** 
23620 5e 54 68 65 20 43 20 61 72 67 75 6d 65 6e 74 20  ^The C argument 
23630 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
23640 20 63 6f 6e 74 65 78 74 20 70 6f 69 6e 74 65 72   context pointer
23650 2e 0a 2a 2a 20 54 68 65 20 50 20 61 6e 64 20 58  ..** The P and X
23660 20 61 72 67 75 6d 65 6e 74 73 20 61 72 65 20 70   arguments are p
23670 6f 69 6e 74 65 72 73 20 77 68 6f 73 65 20 6d 65  ointers whose me
23680 61 6e 69 6e 67 73 20 64 65 70 65 6e 64 20 6f 6e  anings depend on
23690 20 54 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71   T..**.** The sq
236a0 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 29  lite3_trace_v2()
236b0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
236c0 74 65 6e 64 65 64 20 74 6f 20 72 65 70 6c 61 63  tended to replac
236d0 65 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  e the legacy.** 
236e0 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
236f0 74 65 33 5f 74 72 61 63 65 28 29 5d 20 61 6e 64  te3_trace()] and
23700 20 5b 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   [sqlite3_profil
23710 65 28 29 5d 2c 20 62 6f 74 68 20 6f 66 20 77 68  e()], both of wh
23720 69 63 68 0a 2a 2a 20 61 72 65 20 64 65 70 72 65  ich.** are depre
23730 63 61 74 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71  cated..*/.int sq
23740 6c 69 74 65 33 5f 74 72 61 63 65 5f 76 32 28 0a  lite3_trace_v2(.
23750 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 75 6e    sqlite3*,.  un
23760 73 69 67 6e 65 64 20 75 4d 61 73 6b 2c 0a 20 20  signed uMask,.  
23770 69 6e 74 28 2a 78 43 61 6c 6c 62 61 63 6b 29 28  int(*xCallback)(
23780 75 6e 73 69 67 6e 65 64 2c 76 6f 69 64 2a 2c 76  unsigned,void*,v
23790 6f 69 64 2a 2c 76 6f 69 64 2a 29 2c 0a 20 20 76  oid*,void*),.  v
237a0 6f 69 64 20 2a 70 43 74 78 0a 29 3b 0a 0a 2f 2a  oid *pCtx.);../*
237b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
237c0 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
237d0 6c 62 61 63 6b 73 0a 2a 2a 20 4d 45 54 48 4f 44  lbacks.** METHOD
237e0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
237f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f  ^The sqlite3_pro
23800 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c  gress_handler(D,
23810 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65  N,X,P) interface
23820 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
23830 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
23840 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64   X to be invoked
23850 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75   periodically du
23860 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e  ring long runnin
23870 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73  g calls to.** [s
23880 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
23890 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
238a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65   and [sqlite3_ge
238b0 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a  t_table()] for.*
238c0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
238d0 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61  ction D.  An exa
238e0 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69  mple use for thi
238f0 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  s.** interface i
23900 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20  s to keep a GUI 
23910 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61  updated during a
23920 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a   large query..**
23930 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74  .** ^The paramet
23940 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74  er P is passed t
23950 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e  hrough as the on
23960 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ly parameter to 
23970 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  the .** callback
23980 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54   function X.  ^T
23990 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69  he parameter N i
239a0 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d 61 74  s the approximat
239b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20  e number of .** 
239c0 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65  [virtual machine
239d0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74   instructions] t
239e0 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74 65  hat are evaluate
239f0 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65 73  d between succes
23a00 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  sive.** invocati
23a10 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62  ons of the callb
23a20 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20 69 73  ack X.  ^If N is
23a30 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 20 74   less than one t
23a40 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65 73 73  hen the progress
23a50 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73 20 64  .** handler is d
23a60 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
23a70 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
23a80 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
23a90 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
23aa0 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
23ab0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
23ac0 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
23ad0 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
23ae0 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
23af0 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
23b00 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
23b10 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
23b20 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
23b30 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
23b40 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
23b50 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
23b60 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
23b70 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
23b80 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
23b90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
23ba0 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
23bb0 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
23bc0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
23bd0 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
23be0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
23bf0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
23c00 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
23c10 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
23c20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
23c30 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
23c40 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
23c50 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
23c60 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
23c70 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
23c80 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
23c90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
23ca0 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
23cb0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
23cc0 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
23cd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23ce0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
23cf0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
23d00 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
23d10 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23d20 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
23d30 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
23d40 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
23d50 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64 20  aph..**.*/.void 
23d60 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73  sqlite3_progress
23d70 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
23d80 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76  *, int, int(*)(v
23d90 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  oid*), void*);..
23da0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23db0 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61  Opening A New Da
23dc0 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
23dd0 6e 0a 2a 2a 20 43 4f 4e 53 54 52 55 43 54 4f 52  n.** CONSTRUCTOR
23de0 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20  : sqlite3.**.** 
23df0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
23e00 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64  open an SQLite d
23e10 61 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20  atabase file as 
23e20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
23e30 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72   .** filename ar
23e40 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c  gument. ^The fil
23e50 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69  ename argument i
23e60 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
23e70 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71   UTF-8 for.** sq
23e80 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
23e90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23ea0 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36  () and as UTF-16
23eb0 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62   in the native b
23ec0 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72  yte.** order for
23ed0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
23ee0 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65  ). ^(A [database
23ef0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
23f00 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a  dle is usually.*
23f10 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70  * returned in *p
23f20 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20  pDb, even if an 
23f30 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54  error occurs.  T
23f40 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f  he only exceptio
23f50 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20  n is that.** if 
23f60 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65  SQLite is unable
23f70 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
23f80 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
23f90 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
23fa0 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c  ,.** a NULL will
23fb0 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   be written into
23fc0 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f   *ppDb instead o
23fd0 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  f a pointer to t
23fe0 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20  he [sqlite3].** 
23ff0 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74  object.)^ ^(If t
24000 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24010 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72  pened (and/or cr
24020 65 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75  eated) successfu
24030 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51  lly, then.** [SQ
24040 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75  LITE_OK] is retu
24050 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rned.  Otherwise
24060 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
24070 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
24080 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ^The.** [sqlite3
24090 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73  _errmsg()] or [s
240a0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
240b0 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20  )] routines can 
240c0 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
240d0 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20  n.** an English 
240e0 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70  language descrip
240f0 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f  tion of the erro
24100 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  r following a fa
24110 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20  ilure of any.** 
24120 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f  of the sqlite3_o
24130 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a  pen() routines..
24140 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
24150 6c 74 20 65 6e 63 6f 64 69 6e 67 20 77 69 6c 6c  lt encoding will
24160 20 62 65 20 55 54 46 2d 38 20 66 6f 72 20 64 61   be UTF-8 for da
24170 74 61 62 61 73 65 73 20 63 72 65 61 74 65 64 20  tabases created 
24180 75 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  using.** sqlite3
24190 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
241a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 5e  e3_open_v2().  ^
241b0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
241c0 64 69 6e 67 20 66 6f 72 20 64 61 74 61 62 61 73  ding for databas
241d0 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 75 73  es.** created us
241e0 69 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ing sqlite3_open
241f0 31 36 28 29 20 77 69 6c 6c 20 62 65 20 55 54 46  16() will be UTF
24200 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
24210 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
24220 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e  .** Whether or n
24230 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  ot an error occu
24240 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70  rs when it is op
24250 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a  ened, resources.
24260 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
24270 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
24280 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
24290 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65  dle should be re
242a0 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73  leased by.** pas
242b0 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
242c0 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65  te3_close()] whe
242d0 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65  n it is no longe
242e0 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  r required..**.*
242f0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  * The sqlite3_op
24300 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  en_v2() interfac
24310 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c  e works like sql
24320 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65  ite3_open().** e
24330 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63  xcept that it ac
24340 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69  cepts two additi
24350 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20  onal parameters 
24360 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63  for additional c
24370 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74  ontrol.** over t
24380 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20  he new database 
24390 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54  connection.  ^(T
243a0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
243b0 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  er to.** sqlite3
243c0 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74  _open_v2() can t
243d0 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68  ake one of.** th
243e0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
243f0 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e  e values, option
24400 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69  ally combined wi
24410 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  th the .** [SQLI
24420 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
24430 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  , [SQLITE_OPEN_F
24440 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49  ULLMUTEX], [SQLI
24450 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
24460 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  CHE],.** [SQLITE
24470 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
24480 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  HE], and/or [SQL
24490 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c  ITE_OPEN_URI] fl
244a0 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  ags:)^.**.** <dl
244b0 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  >.** ^(<dt>[SQLI
244c0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
244d0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
244e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
244f0 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c  ened in read-onl
24500 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  y mode.  If the 
24510 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f  database does no
24520 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69  t.** already exi
24530 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20  st, an error is 
24540 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
24550 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
24560 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
24570 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ITE]</dt>.** <dd
24580 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
24590 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
245a0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20  ing and writing 
245b0 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20  if possible, or 
245c0 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20  reading.** only 
245d0 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77  if the file is w
245e0 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62  rite protected b
245f0 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  y the operating 
24600 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68  system.  In eith
24610 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64  er.** case the d
24620 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72  atabase must alr
24630 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65  eady exist, othe
24640 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69  rwise an error i
24650 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
24660 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
24670 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24680 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45  WRITE] | [SQLITE
24690 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64  _OPEN_CREATE]</d
246a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
246b0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
246c0 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
246d0 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73   writing, and is
246e0 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69   created if.** i
246f0 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61  t does not alrea
24700 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69  dy exist. This i
24710 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74  s the behavior t
24720 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73  hat is always us
24730 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  ed for.** sqlite
24740 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
24750 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f  ite3_open16().</
24760 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
24770 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20  *.** If the 3rd 
24780 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
24790 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
247a0 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65  s not one of the
247b0 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  .** combinations
247c0 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74   shown above opt
247d0 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64  ionally combined
247e0 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b   with other.** [
247f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
24800 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50  ONLY | SQLITE_OP
24810 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68  EN_* bits].** th
24820 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
24830 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
24840 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  .** ^If the [SQL
24850 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
24860 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74  ] flag is set, t
24870 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
24880 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
24890 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74  pens in the mult
248a0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
248b0 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e  ing mode] as lon
248c0 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d  g as the single-
248d0 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68  thread.** mode h
248e0 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20  as not been set 
248f0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
24900 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20  or start-time.  
24910 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ^If the.** [SQLI
24920 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45  TE_OPEN_FULLMUTE
24930 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74  X] flag is set t
24940 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
24950 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
24960 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69  s.** in the seri
24970 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
24980 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73  g mode] unless s
24990 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73  ingle-thread was
249a0 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
249b0 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69  elected at compi
249c0 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
249d0 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b  -time..** ^The [
249e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
249f0 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61  EDCACHE] flag ca
24a00 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73  uses the databas
24a10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20  e connection to 
24a20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74  be.** eligible t
24a30 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61  o use [shared ca
24a40 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72  che mode], regar
24a50 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
24a60 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a   or not shared.*
24a70 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c  * cache is enabl
24a80 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
24a90 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f  3_enable_shared_
24aa0 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a  cache()].  ^The.
24ab0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
24ac0 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c  PRIVATECACHE] fl
24ad0 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61  ag causes the da
24ae0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24af0 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74  n to not.** part
24b00 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72  icipate in [shar
24b10 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65  ed cache mode] e
24b20 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61  ven if it is ena
24b30 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
24b40 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
24b50 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
24b60 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61  n_v2() is the na
24b70 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  me of the.** [sq
24b80 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
24b90 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74  t that defines t
24ba0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
24bb0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
24bc0 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61  at.** the new da
24bd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
24be0 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e  n should use.  ^
24bf0 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
24c00 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20  rameter is.** a 
24c10 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
24c20 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  n the default [s
24c30 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
24c40 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  ct is used..**.*
24c50 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
24c60 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22  me is ":memory:"
24c70 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
24c80 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d  , temporary in-m
24c90 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a  emory database.*
24ca0 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72  * is created for
24cb0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e   the connection.
24cc0 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72    ^This in-memor
24cd0 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  y database will 
24ce0 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74  vanish when.** t
24cf0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
24d00 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
24d10 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
24d20 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
24d30 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f  ht.** make use o
24d40 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65  f additional spe
24d50 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74  cial filenames t
24d60 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74  hat begin with t
24d70 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72  he ":" character
24d80 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d  ..** It is recom
24d90 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e  mended that when
24da0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
24db0 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f  name actually do
24dc0 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a  es begin with.**
24dd0 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72   a ":" character
24de0 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66   you should pref
24df0 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ix the filename 
24e00 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20  with a pathname 
24e10 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20  such as.** "./" 
24e20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69  to avoid ambigui
24e30 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ty..**.** ^If th
24e40 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e  e filename is an
24e50 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74   empty string, t
24e60 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
24e70 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64  emporary.** on-d
24e80 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c  isk database wil
24e90 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e  l be created.  ^
24ea0 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74  This private dat
24eb0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a  abase will be.**
24ec0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64   automatically d
24ed0 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61  eleted as soon a
24ee0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
24ef0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
24f00 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49  sed..**.** [[URI
24f10 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71   filenames in sq
24f20 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c  lite3_open()]] <
24f30 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73  h3>URI Filenames
24f40 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  </h3>.**.** ^If 
24f50 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69  [URI filename] i
24f60 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
24f70 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
24f80 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
24f90 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
24fa0 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
24fb0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
24fc0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
24fd0 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
24fe0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
24ff0 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
25000 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
25010 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
25020 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65  is.** set in the
25030 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
25040 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
25050 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20  _v2(), or if it 
25060 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62  has.** been enab
25070 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69  led globally usi
25080 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43  ng the [SQLITE_C
25090 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f  ONFIG_URI] optio
250a0 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73  n with the.** [s
250b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
250c0 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68   method or by th
250d0 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  e [SQLITE_USE_UR
250e0 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  I] compile-time 
250f0 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66  option..** As of
25100 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
25110 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e  3.7.7, URI filen
25120 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
25130 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66  on is turned off
25140 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20  .** by default, 
25150 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61  but future relea
25160 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ses of SQLite mi
25170 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66  ght enable URI f
25180 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72  ilename.** inter
25190 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
251a0 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
251b0 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
251c0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
251d0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
251e0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
251f0 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
25200 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
25210 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
25220 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
25230 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
25240 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
25250 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
25260 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
25270 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
25280 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
25290 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
252a0 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
252b0 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
252c0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
252d0 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
252e0 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
252f0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
25300 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
25310 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
25320 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
25330 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
25340 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
25350 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
25360 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
25370 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
25380 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
25390 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
253a0 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
253b0 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
253c0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
253d0 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
253e0 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
253f0 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
25400 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
25410 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
25420 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
25430 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
25440 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
25450 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
25460 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
25470 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
25480 20 0a 2a 2a 20 5e 28 4f 6e 20 77 69 6e 64 6f 77   .** ^(On window
25490 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
254a0 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
254b0 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
254c0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
254d0 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
254e0 3a 22 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 63  :").)^.**.** [[c
254f0 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61  ore URI query pa
25500 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68  rameters]].** Th
25510 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
25520 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63  t of a URI may c
25530 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72  ontain parameter
25540 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72  s that are inter
25550 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72  preted.** either
25560 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c   by SQLite itsel
25570 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20  f, or by a [VFS 
25580 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70  | custom VFS imp
25590 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a  lementation]..**
255a0 20 53 51 4c 69 74 65 20 61 6e 64 20 69 74 73 20   SQLite and its 
255b0 62 75 69 6c 74 2d 69 6e 20 5b 56 46 53 65 73 5d  built-in [VFSes]
255c0 20 69 6e 74 65 72 70 72 65 74 20 74 68 65 0a 2a   interpret the.*
255d0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 71 75 65 72  * following quer
255e0 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
255f0 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
25600 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
25610 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
25620 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
25630 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
25640 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
25650 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
25660 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
25670 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
25680 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
25690 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
256a0 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
256b0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
256c0 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
256d0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
256e0 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
256f0 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
25700 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
25710 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
25720 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
25730 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
25740 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
25750 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
25760 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
25770 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
25780 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
25790 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
257a0 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
257b0 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
257c0 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
257d0 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
257e0 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
257f0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
25800 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
25810 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
25820 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
25830 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
25840 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
25850 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
25860 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
25870 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
25880 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
25890 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
258a0 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
258b0 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
258c0 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
258d0 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
258e0 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
258f0 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
25900 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
25910 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
25920 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
25930 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
25940 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
25950 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
25960 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
25970 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74  open_v2(). ^If t
25980 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
25990 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20  s set to .**    
259a0 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20   "rw", then the 
259b0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
259c0 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74  ed for read-writ
259d0 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74  e (but not creat
259e0 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  e) .**     acces
259f0 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f  s, as if SQLITE_
25a00 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28  OPEN_READWRITE (
25a10 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f  but not SQLITE_O
25a20 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20  PEN_CREATE) had 
25a30 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74  .**     been set
25a40 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69  . ^Value "rwc" i
25a50 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
25a60 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a  setting both .**
25a70 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
25a80 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53  _READWRITE and S
25a90 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
25aa0 45 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  E.  ^If the mode
25ab0 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
25ac0 20 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79    set to "memory
25ad0 22 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69  " then a pure [i
25ae0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
25af0 65 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65  e] that never re
25b00 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72  ads.**     or wr
25b10 69 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69  ites from disk i
25b20 73 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61  s used. ^It is a
25b30 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69  n error to speci
25b40 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a  fy a value for.*
25b50 2a 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70  *     the mode p
25b60 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73  arameter that is
25b70 20 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76   less restrictiv
25b80 65 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63  e than that spec
25b90 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
25ba0 74 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64  the flags passed
25bb0 20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61   in the third pa
25bc0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
25bd0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
25be0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61  .**   <li> <b>ca
25bf0 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61  che</b>: ^The ca
25c00 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  che parameter ma
25c10 79 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68  y be set to eith
25c20 65 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a  er "shared" or.*
25c30 2a 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e  *     "private".
25c40 20 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20   ^Setting it to 
25c50 22 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69  "shared" is equi
25c60 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
25c70 67 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c  g the.**     SQL
25c80 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25c90 41 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20  ACHE bit in the 
25ca0 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70  flags argument p
25cb0 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20  assed to.**     
25cc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25cd0 29 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20  ). ^Setting the 
25ce0 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20  cache parameter 
25cf0 74 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20  to "private" is 
25d00 0a 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65  .**     equivale
25d10 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
25d20 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
25d30 49 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a  IVATECACHE bit..
25d40 2a 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74  **     ^If sqlit
25d50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
25d60 75 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61  used and the "ca
25d70 63 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69  che" parameter i
25d80 73 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20  s present in.** 
25d90 20 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61      a URI filena
25da0 6d 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76  me, its value ov
25db0 65 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61  errides any beha
25dc0 76 69 6f 72 20 72 65 71 75 65 73 74 65 64 20 62  vior requested b
25dd0 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
25de0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
25df0 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
25e00 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25e10 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a  ACHE flag..**.**
25e20 20 20 3c 6c 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f    <li> <b>psow</
25e30 62 3e 3a 20 5e 54 68 65 20 70 73 6f 77 20 70 61  b>: ^The psow pa
25e40 72 61 6d 65 74 65 72 20 69 6e 64 69 63 61 74 65  rameter indicate
25e50 73 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  s whether or not
25e60 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b 70 6f 77   the.**     [pow
25e70 65 72 73 61 66 65 20 6f 76 65 72 77 72 69 74 65  ersafe overwrite
25e80 5d 20 70 72 6f 70 65 72 74 79 20 64 6f 65 73 20  ] property does 
25e90 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 6c  or does not appl
25ea0 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20 20 20 20  y to the.**     
25eb0 73 74 6f 72 61 67 65 20 6d 65 64 69 61 20 6f 6e  storage media on
25ec0 20 77 68 69 63 68 20 74 68 65 20 64 61 74 61 62   which the datab
25ed0 61 73 65 20 66 69 6c 65 20 72 65 73 69 64 65 73  ase file resides
25ee0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
25ef0 3e 6e 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68  >nolock</b>: ^Th
25f00 65 20 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74  e nolock paramet
25f10 65 72 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20  er is a boolean 
25f20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a  query parameter.
25f30 2a 2a 20 20 20 20 20 77 68 69 63 68 20 69 66 20  **     which if 
25f40 73 65 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c  set disables fil
25f50 65 20 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c  e locking in rol
25f60 6c 62 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f  lback journal mo
25f70 64 65 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20  des.  This.**   
25f80 20 20 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20    is useful for 
25f90 61 63 63 65 73 73 69 6e 67 20 61 20 64 61 74 61  accessing a data
25fa0 62 61 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79  base on a filesy
25fb0 73 74 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e  stem that does n
25fc0 6f 74 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72  ot.**     suppor
25fd0 74 20 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74  t locking.  Caut
25fe0 69 6f 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63  ion:  Database c
25ff0 6f 72 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20  orruption might 
26000 72 65 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a  result if two.**
26010 20 20 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f       or more pro
26020 63 65 73 73 65 73 20 77 72 69 74 65 20 74 6f 20  cesses write to 
26030 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
26040 65 20 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66  e and any one of
26050 20 74 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72   those.**     pr
26060 6f 63 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c  ocesses uses nol
26070 6f 63 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c  ock=1..**.**  <l
26080 69 3e 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c  i> <b>immutable<
26090 2f 62 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61  /b>: ^The immuta
260a0 62 6c 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ble parameter is
260b0 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
260c0 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65  .**     paramete
260d0 72 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73  r that indicates
260e0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
260f0 73 65 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65  se file is store
26100 64 20 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64  d on.**     read
26110 2d 6f 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57  -only media.  ^W
26120 68 65 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73  hen immutable is
26130 20 73 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73   set, SQLite ass
26140 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
26150 20 20 20 20 20 64 61 74 61 62 61 73 65 20 66 69       database fi
26160 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  le cannot be cha
26170 6e 67 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20  nged, even by a 
26180 70 72 6f 63 65 73 73 20 77 69 74 68 20 68 69 67  process with hig
26190 68 65 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69  her.**     privi
261a0 6c 65 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65  lege, and so the
261b0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
261c0 6e 65 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e  ned read-only an
261d0 64 20 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a  d all locking.**
261e0 20 20 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20       and change 
261f0 64 65 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73  detection is dis
26200 61 62 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a  abled.  Caution:
26210 20 53 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d   Setting the imm
26220 75 74 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72  utable.**     pr
26230 6f 70 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61  operty on a data
26240 62 61 73 65 20 66 69 6c 65 20 74 68 61 74 20 64  base file that d
26250 6f 65 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e  oes in fact chan
26260 67 65 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a  ge can result.**
26270 20 20 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63       in incorrec
26280 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  t query results 
26290 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43  and/or [SQLITE_C
262a0 4f 52 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a  ORRUPT] errors..
262b0 2a 2a 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a  **     See also:
262c0 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49   [SQLITE_IOCAP_I
262d0 4d 4d 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20  MMUTABLE]..**   
262e0 20 20 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a      .** </ul>.**
262f0 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
26300 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
26310 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
26320 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
26330 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
26340 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
26350 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
26360 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
26370 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
26380 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
26390 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
263a0 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
263b0 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
263c0 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
263d0 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
263e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
263f0 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
26400 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
26410 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
26420 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
26430 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
26440 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
26450 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
26460 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
26470 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
26480 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
26490 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
264a0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
264b0 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
264c0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
264d0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
264e0 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
264f0 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
26500 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
26510 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
26520 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
26530 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
26540 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
26550 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
26560 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
26570 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
26580 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
26590 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
265a0 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
265b0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
265c0 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
265d0 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
265e0 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
265f0 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
26600 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
26610 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
26620 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
26630 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
26640 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
26650 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
26660 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
26670 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
26680 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
26690 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
266a0 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
266b0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
266c0 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
266d0 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
266e0 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
266f0 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
26700 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
26710 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
26720 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
26730 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
26740 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
26750 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
26760 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
26770 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
26780 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
26790 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
267a0 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
267b0 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
267c0 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
267d0 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
267e0 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
267f0 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
26800 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
26810 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
26820 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
26830 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
26840 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
26850 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
26860 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
26870 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
26880 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
26890 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
268a0 66 73 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20  fs=unix-dotfile 
268b0 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
268c0 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
268d0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
268e0 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
268f0 20 56 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69   VFS "unix-dotfi
26900 6c 65 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  le".**          
26910 74 68 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69  that uses dot-fi
26920 6c 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  les in place of 
26930 70 6f 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c  posix advisory l
26940 6f 63 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c  ocking..** <tr><
26950 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
26960 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c  ?mode=readonly <
26970 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
26980 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64   An error. "read
26990 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76  only" is not a v
269a0 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20  alid option for 
269b0 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d  the "mode" param
269c0 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eter..** </table
269d0 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78  >.**.** ^URI hex
269e0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
269f0 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29 20  sequences (%HH) 
26a00 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77 69  are supported wi
26a10 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e  thin the path an
26a20 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f  d.** query compo
26a30 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20  nents of a URI. 
26a40 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  A hexadecimal es
26a50 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f  cape sequence co
26a60 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70  nsists of a.** p
26a70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25  ercent sign - "%
26a80 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  " - followed by 
26a90 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61  exactly two hexa
26aa0 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a  decimal digits .
26ab0 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e  ** specifying an
26ac0 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42   octet value. ^B
26ad0 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f  efore the path o
26ae0 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  r query componen
26af0 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66  ts of a.** URI f
26b00 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65  ilename are inte
26b10 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61 72  rpreted, they ar
26b20 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20  e encoded using 
26b30 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a  UTF-8 and all .*
26b40 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  * hexadecimal es
26b50 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 72  cape sequences r
26b60 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e  eplaced by a sin
26b70 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e  gle byte contain
26b80 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  ing the.** corre
26b90 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20  sponding octet. 
26ba0 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73 20  If this process 
26bb0 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76  generates an inv
26bc0 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64  alid UTF-8 encod
26bd0 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75  ing,.** the resu
26be0 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
26bf0 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
26c00 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72   to Windows user
26c10 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f  s:</b>  The enco
26c20 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68  ding used for th
26c30 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
26c40 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  ent.** of sqlite
26c50 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
26c60 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d  ite3_open_v2() m
26c70 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f  ust be UTF-8, no
26c80 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f  t whatever.** co
26c90 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65 6e  depage is curren
26ca0 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69  tly defined.  Fi
26cb0 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69  lenames containi
26cc0 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c  ng international
26cd0 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d  .** characters m
26ce0 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64  ust be converted
26cf0 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20   to UTF-8 prior 
26d00 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20  to passing them 
26d10 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
26d20 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
26d30 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
26d40 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
26d50 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
26d60 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
26d70 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
26d80 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
26d90 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
26da0 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  g sqlite3_open()
26db0 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   or sqlite3_open
26dc0 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73  _v2().  Otherwis
26dd0 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
26de0 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
26df0 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
26e00 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
26e10 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53  ay fail..**.** S
26e20 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
26e30 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
26e40 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
26e50 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63  _open(.  const c
26e60 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
26e70 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
26e80 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
26e90 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
26ea0 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
26eb0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
26ec0 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  dle */.);.int sq
26ed0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20  lite3_open16(.  
26ee0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65  const void *file
26ef0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
26f00 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
26f10 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74  F-16) */.  sqlit
26f20 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
26f30 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
26f40 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
26f50 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  ;.int sqlite3_op
26f60 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
26f70 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
26f80 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
26f90 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
26fa0 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
26fb0 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
26fc0 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
26fd0 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
26fe0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
26ff0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
27000 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
27010 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
27020 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
27030 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
27040 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
27050 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49  n Values For URI
27060 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a   Parameters.**.*
27070 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69 6c  * These are util
27080 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73  ity routines, us
27090 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
270a0 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
270b0 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65  t check.** to se
270c0 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65 20  e if a database 
270d0 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20 74  file was a URI t
270e0 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20  hat contained a 
270f0 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20 0a  specific query .
27100 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e  ** parameter, an
27110 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20  d if so obtains 
27120 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61  the value of tha
27130 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  t query paramete
27140 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73  r..**.** If F is
27150 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
27160 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70  lename pointer p
27170 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
27180 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66  Open() method of
27190 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65   .** a VFS imple
271a0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74  mentation when t
271b0 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
271c0 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61  er to xOpen() ha
271d0 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72  s one or .** mor
271e0 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  e of the [SQLITE
271f0 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53  _OPEN_URI] or [S
27200 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
27210 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64  DB] bits set and
27220 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d  .** P is the nam
27230 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 70  e of the query p
27240 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a  arameter, then.*
27250 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  * sqlite3_uri_pa
27260 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
27270 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f  urns the value o
27280 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d  f the P.** param
27290 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73 74  eter if it exist
272a0 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s or a NULL poin
272b0 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  ter if P does no
272c0 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a  t appear as a .*
272d0 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
272e0 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73  r on F.  If P is
272f0 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65 74   a query paramet
27300 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e  er of F.** has n
27310 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65  o explicit value
27320 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
27330 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50  ri_parameter(F,P
27340 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70  ) returns.** a p
27350 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70  ointer to an emp
27360 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ty string..**.**
27370 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
27380 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
27390 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20  routine assumes 
273a0 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c  that P is a bool
273b0 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ean.** parameter
273c0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75   and returns tru
273d0 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28  e (1) or false (
273e0 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  0) according to 
273f0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  the value.** of 
27400 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  P.  The sqlite3_
27410 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
27420 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  B) routine retur
27430 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20 74  ns true (1) if t
27440 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71  he.** value of q
27450 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
27460 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22   is one of "yes"
27470 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e  , "true", or "on
27480 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65  " in any.** case
27490 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
274a0 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
274b0 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20  on-zero number. 
274c0 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33   The .** sqlite3
274d0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
274e0 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ,B) routines ret
274f0 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69  urns false (0) i
27500 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a  f the value of.*
27510 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  * query paramete
27520 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e  r P is one of "n
27530 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20  o", "false", or 
27540 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73  "off" in any cas
27550 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76  e or.** if the v
27560 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68  alue begins with
27570 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e   a numeric zero.
27580 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20    If P is not a 
27590 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
275a0 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68  er on F or if th
275b0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
275c0 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61  does not match a
275d0 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f  ny of the.** abo
275e0 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ve, then sqlite3
275f0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
27600 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d  ,B) returns (B!=
27610 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  0)..**.** The sq
27620 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28  lite3_uri_int64(
27630 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63  F,P,D) routine c
27640 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c 75  onverts the valu
27650 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a  e of P into a.**
27660 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
27670 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75 72  nteger and retur
27680 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c  ns that integer,
27690 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73 20   or D if P does 
276a0 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49  not.** exist.  I
276b0 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  f the value of P
276c0 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74   is something ot
276d0 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65  her than an inte
276e0 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72  ger, then.** zer
276f0 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
27700 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20  * .** If F is a 
27710 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
27720 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
27730 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
27740 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a  turns NULL and.*
27750 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
27760 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
27770 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73  urns B.  If F is
27780 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e   not a NULL poin
27790 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f  ter and.** is no
277a0 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  t a database fil
277b0 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74  e pathname point
277c0 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 70  er that SQLite p
277d0 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78  assed into the x
277e0 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68  Open.** VFS meth
277f0 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  od, then the beh
27800 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f  avior of this ro
27810 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e  utine is undefin
27820 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a  ed and probably.
27830 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ** undesirable..
27840 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
27850 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
27860 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20  eter(const char 
27870 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73  *zFilename, cons
27880 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b  t char *zParam);
27890 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69  .int sqlite3_uri
278a0 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
278b0 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
278c0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
278d0 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73  int bDefault);.s
278e0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
278f0 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63  ite3_uri_int64(c
27900 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73  onst char*, cons
27910 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33  t char*, sqlite3
27920 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  _int64);.../*.**
27930 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
27940 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
27950 67 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ges.** METHOD: s
27960 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 49 66  qlite3.**.** ^If
27970 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
27980 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
27990 61 6c 6c 20 61 73 73 6f 63 69 61 74 65 64 20 77  all associated w
279a0 69 74 68 20 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ith .** [databas
279b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
279c0 66 61 69 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  failed, then the
279d0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
279e0 28 44 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  (D) interface.**
279f0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
27a00 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64  eric [result cod
27a10 65 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20  e] or [extended 
27a20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
27a30 20 74 68 61 74 0a 2a 2a 20 41 50 49 20 63 61 6c   that.** API cal
27a40 6c 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6d 6f 73  l..** If the mos
27a50 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
27a60 6c 20 77 61 73 20 73 75 63 63 65 73 73 66 75 6c  l was successful
27a70 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
27a80 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
27a90 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
27aa0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  ) is undefined..
27ab0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
27ac0 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
27ad0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
27ae0 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
27af0 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
27b00 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
27b10 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
27b20 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
27b30 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
27b40 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
27b50 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
27b60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
27b70 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
27b80 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
27b90 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
27ba0 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
27bb0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
27bc0 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
27bd0 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
27be0 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
27bf0 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
27c00 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
27c10 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
27c20 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
27c30 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
27c40 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
27c50 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
27c60 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
27c70 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
27c80 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
27c90 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
27ca0 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
27cb0 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
27cc0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
27cd0 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
27ce0 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
27cf0 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ns.)^.**.** ^The
27d00 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
27d10 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
27d20 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d  rns the English-
27d30 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a  language text.**
27d40 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
27d50 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  the [result code
27d60 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20  ], as UTF-8..** 
27d70 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
27d80 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
27d90 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
27da0 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  aged internally.
27db0 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  ** and must not 
27dc0 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20  be freed by the 
27dd0 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a  application)^..*
27de0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
27df0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
27e00 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
27e10 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
27e20 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
27e30 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
27e40 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
27e50 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
27e60 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
27e70 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
27e80 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
27e90 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
27ea0 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
27eb0 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
27ec0 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
27ed0 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
27ee0 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
27ef0 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
27f00 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
27f10 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
27f20 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
27f30 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
27f40 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
27f50 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
27f60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
27f70 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
27f80 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
27f90 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
27fa0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
27fb0 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
27fc0 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
27fd0 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
27fe0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
27ff0 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
28000 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
28010 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
28020 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
28030 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
28040 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
28050 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
28060 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
28070 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
28080 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
28090 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
280a0 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
280b0 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
280c0 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
280d0 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
280e0 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
280f0 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
28100 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71  e set..*/.int sq
28110 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71  lite3_errcode(sq
28120 6c 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20  lite3 *db);.int 
28130 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
28140 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
28150 20 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61   *db);.const cha
28160 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
28170 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e  g(sqlite3*);.con
28180 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
28190 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
281a0 33 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  3*);.const char 
281b0 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28  *sqlite3_errstr(
281c0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
281d0 49 33 52 45 46 3a 20 50 72 65 70 61 72 65 64 20  I3REF: Prepared 
281e0 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
281f0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
28200 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28210 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
28220 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
28230 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
28240 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
28250 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
28260 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  L statement that
28270 0a 2a 2a 20 68 61 73 20 62 65 65 6e 20 63 6f 6d  .** has been com
28280 70 69 6c 65 64 20 69 6e 74 6f 20 62 69 6e 61 72  piled into binar
28290 79 20 66 6f 72 6d 20 61 6e 64 20 69 73 20 72 65  y form and is re
282a0 61 64 79 20 74 6f 20 62 65 20 65 76 61 6c 75 61  ady to be evalua
282b0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 6e 6b  ted..**.** Think
282c0 20 6f 66 20 65 61 63 68 20 53 51 4c 20 73 74 61   of each SQL sta
282d0 74 65 6d 65 6e 74 20 61 73 20 61 20 73 65 70 61  tement as a sepa
282e0 72 61 74 65 20 63 6f 6d 70 75 74 65 72 20 70 72  rate computer pr
282f0 6f 67 72 61 6d 2e 20 20 54 68 65 0a 2a 2a 20 6f  ogram.  The.** o
28300 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
28310 20 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65 2e   is source code.
28320 20 20 41 20 70 72 65 70 61 72 65 64 20 73 74 61    A prepared sta
28330 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 0a 2a  tement object .*
28340 2a 20 69 73 20 74 68 65 20 63 6f 6d 70 69 6c 65  * is the compile
28350 64 20 6f 62 6a 65 63 74 20 63 6f 64 65 2e 20 20  d object code.  
28360 41 6c 6c 20 53 51 4c 20 6d 75 73 74 20 62 65 20  All SQL must be 
28370 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
28380 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
28390 74 65 6d 65 6e 74 20 62 65 66 6f 72 65 20 69 74  tement before it
283a0 20 63 61 6e 20 62 65 20 72 75 6e 2e 0a 2a 2a 0a   can be run..**.
283b0 2a 2a 20 54 68 65 20 6c 69 66 65 2d 63 79 63 6c  ** The life-cycl
283c0 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 20  e of a prepared 
283d0 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
283e0 20 75 73 75 61 6c 6c 79 20 67 6f 65 73 20 6c 69   usually goes li
283f0 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
28400 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61  ol>.** <li> Crea
28410 74 65 20 74 68 65 20 70 72 65 70 61 72 65 64 20  te the prepared 
28420 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
28430 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
28440 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2e 0a 2a  prepare_v2()]..*
28450 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75  * <li> Bind valu
28460 65 73 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  es to [parameter
28470 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  s] using the sql
28480 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a  ite3_bind_*().**
28490 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73        interfaces
284a0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68  ..** <li> Run th
284b0 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67  e SQL by calling
284c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
284d0 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69  ] one or more ti
284e0 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73  mes..** <li> Res
284f0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
28500 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
28510 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28520 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a  ] then go back.*
28530 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20 32  *      to step 2
28540 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20  .  Do this zero 
28550 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
28560 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74  * <li> Destroy t
28570 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
28580 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
28590 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  e()]..** </ol>.*
285a0 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
285b0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
285c0 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
285d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
285e0 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 20  -time Limits.** 
285f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 0a  METHOD: sqlite3.
28600 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74  **.** ^(This int
28610 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68  erface allows th
28620 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75  e size of variou
28630 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20  s constructs to 
28640 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e  be limited.** on
28650 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79   a connection by
28660 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69   connection basi
28670 73 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61  s.  The first pa
28680 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
28690 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
286a0 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69  ection] whose li
286b0 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74  mit is to be set
286c0 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68   or queried.  Th
286d0 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
286e0 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20  meter is one of 
286f0 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67  the [limit categ
28700 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69  ories] that defi
28710 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66  ne a.** class of
28720 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
28730 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20  e size limited. 
28740 20 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   The third param
28750 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e  eter is the.** n
28760 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61  ew limit for tha
28770 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a  t construct.)^.*
28780 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77  *.** ^If the new
28790 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61   limit is a nega
287a0 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65  tive number, the
287b0 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e   limit is unchan
287c0 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61  ged..** ^(For ea
287d0 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  ch limit categor
287e0 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c  y SQLITE_LIMIT_<
287f0 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65  i>NAME</i> there
28800 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74   is a .** [limit
28810 73 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62  s | hard upper b
28820 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20  ound].** set at 
28830 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20  compile-time by 
28840 61 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  a C preprocessor
28850 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a   macro called.**
28860 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54   [limits | SQLIT
28870 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  E_MAX_<i>NAME</i
28880 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49  >]..** (The "_LI
28890 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d  MIT_" in the nam
288a0 65 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20  e is changed to 
288b0 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e  "_MAX_".))^.** ^
288c0 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72  Attempts to incr
288d0 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f  ease a limit abo
288e0 76 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65  ve its hard uppe
288f0 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73  r bound are.** s
28900 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65  ilently truncate
28910 64 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70  d to the hard up
28920 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a  per bound..**.**
28930 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20   ^Regardless of 
28940 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
28950 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61  he limit was cha
28960 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73  nged, the .** [s
28970 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20  qlite3_limit()] 
28980 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
28990 73 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  s the prior valu
289a0 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a  e of the limit..
289b0 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69  ** ^Hence, to fi
289c0 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  nd the current v
289d0 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20  alue of a limit 
289e0 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67  without changing
289f0 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69   it,.** simply i
28a00 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72  nvoke this inter
28a10 66 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68  face with the th
28a20 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65  ird parameter se
28a30 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52  t to -1..**.** R
28a40 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61  un-time limits a
28a50 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
28a60 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69  use in applicati
28a70 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a  ons that manage.
28a80 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77  ** both their ow
28a90 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  n internal datab
28aa0 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74  ase and also dat
28ab0 61 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20  abases that are 
28ac0 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79  controlled.** by
28ad0 20 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72   untrusted exter
28ae0 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e  nal sources.  An
28af0 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61   example applica
28b00 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a  tion might be a.
28b10 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74  ** web browser t
28b20 68 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20  hat has its own 
28b30 64 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74  databases for st
28b40 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e  oring history an
28b50 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61  d.** separate da
28b60 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c  tabases controll
28b70 65 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74  ed by JavaScript
28b80 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f   applications do
28b90 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20  wnloaded.** off 
28ba0 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54  the Internet.  T
28bb0 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  he internal data
28bc0 62 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76  bases can be giv
28bd0 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c  en the.** large,
28be0 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e   default limits.
28bf0 20 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61    Databases mana
28c00 67 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20  ged by external 
28c10 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62  sources can.** b
28c20 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61  e given much sma
28c30 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69  ller limits desi
28c40 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20  gned to prevent 
28c50 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76  a denial of serv
28c60 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20  ice.** attack.  
28c70 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74  Developers might
28c80 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73   also want to us
28c90 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  e the [sqlite3_s
28ca0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
28cb0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f  .** interface to
28cc0 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c   further control
28cd0 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20   untrusted SQL. 
28ce0 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
28cf0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65   database.** cre
28d00 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75  ated by an untru
28d10 73 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20  sted script can 
28d20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69  be contained usi
28d30 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70  ng the.** [max_p
28d40 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
28d50 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72  MA]..**.** New r
28d60 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61  un-time limit ca
28d70 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20  tegories may be 
28d80 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
28d90 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74  releases..*/.int
28da0 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73   sqlite3_limit(s
28db0 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c  qlite3*, int id,
28dc0 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f   int newVal);../
28dd0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28de0 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61  un-Time Limit Ca
28df0 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57  tegories.** KEYW
28e00 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74  ORDS: {limit cat
28e10 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63  egory} {*limit c
28e20 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a  ategories}.**.**
28e30 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
28e40 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20   define various 
28e50 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69  performance limi
28e60 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  ts.** that can b
28e70 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e  e lowered at run
28e80 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c  -time using [sql
28e90 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a  ite3_limit()]..*
28ea0 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f  * The synopsis o
28eb0 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f  f the meanings o
28ec0 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69  f the various li
28ed0 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65  mits is shown be
28ee0 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e  low..** Addition
28ef0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  al information i
28f00 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b  s available at [
28f10 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20  limits | Limits 
28f20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a  in SQLite]..**.*
28f30 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49  * <dl>.** [[SQLI
28f40 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d  TE_LIMIT_LENGTH]
28f50 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
28f60 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  IMIT_LENGTH</dt>
28f70 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28f80 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20  mum size of any 
28f90 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f  string or BLOB o
28fa0 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20  r table row, in 
28fb0 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a  bytes.<dd>)^.**.
28fc0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
28fd0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e  T_SQL_LENGTH]] ^
28fe0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
28ff0 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74  T_SQL_LENGTH</dt
29000 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29010 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61  imum length of a
29020 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  n SQL statement,
29030 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29   in bytes.</dd>)
29040 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
29050 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20  _LIMIT_COLUMN]] 
29060 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
29070 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a  IT_COLUMN</dt>.*
29080 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
29090 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
290a0 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64  mns in a table d
290b0 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20  efinition or in 
290c0 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65  the.** result se
290d0 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20  t of a [SELECT] 
290e0 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  or the maximum n
290f0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
29100 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20   in an index.** 
29110 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42  or in an ORDER B
29120 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c  Y or GROUP BY cl
29130 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ause.</dd>)^.**.
29140 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
29150 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e  T_EXPR_DEPTH]] ^
29160 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29170 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74  T_EXPR_DEPTH</dt
29180 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
29190 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68  imum depth of th
291a0 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20  e parse tree on 
291b0 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c  any expression.<
291c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
291d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
291e0 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28  OUND_SELECT]] ^(
291f0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
29200 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
29210 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
29220 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
29230 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f  of terms in a co
29240 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74  mpound SELECT st
29250 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a  atement.</dd>)^.
29260 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
29270 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e  IMIT_VDBE_OP]] ^
29280 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
29290 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
292a0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
292b0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
292c0 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
292d0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
292e0 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
292f0 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
29300 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  L statement.  Th
29310 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  is limit is not 
29320 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66  currently.** enf
29330 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68  orced, though th
29340 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65  at might be adde
29350 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  d in some future
29360 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
29370 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  QLite.</dd>)^.**
29380 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
29390 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d  IT_FUNCTION_ARG]
293a0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
293b0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
293c0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  G</dt>.** <dd>Th
293d0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
293e0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e   of arguments on
293f0 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64   a function.</dd
29400 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
29410 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
29420 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  D]] ^(<dt>SQLITE
29430 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c  _LIMIT_ATTACHED<
29440 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
29450 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
29460 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61  f [ATTACH | atta
29470 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e  ched databases].
29480 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  )^</dd>.**.** [[
29490 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
294a0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
294b0 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
294c0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
294d0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
294e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
294f0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
29500 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
29510 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
29520 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
29530 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
29540 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
29550 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
29560 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  UMBER]].** ^(<dt
29570 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  >SQLITE_LIMIT_VA
29580 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64  RIABLE_NUMBER</d
29590 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
295a0 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62  ximum index numb
295b0 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d  er of any [param
295c0 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20  eter] in an SQL 
295d0 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a  statement.)^.**.
295e0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
295f0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d  T_TRIGGER_DEPTH]
29600 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
29610 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
29620 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
29630 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
29640 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f   of recursion fo
29650 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e  r triggers.</dd>
29660 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
29670 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52 5f 54  E_LIMIT_WORKER_T
29680 48 52 45 41 44 53 5d 5d 20 5e 28 3c 64 74 3e 53  HREADS]] ^(<dt>S
29690 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b  QLITE_LIMIT_WORK
296a0 45 52 5f 54 48 52 45 41 44 53 3c 2f 64 74 3e 0a  ER_THREADS</dt>.
296b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
296c0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 75 78  um number of aux
296d0 69 6c 69 61 72 79 20 77 6f 72 6b 65 72 20 74 68  iliary worker th
296e0 72 65 61 64 73 20 74 68 61 74 20 61 20 73 69 6e  reads that a sin
296f0 67 6c 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  gle.** [prepared
29700 20 73 74 61 74 65 6d 65 6e 74 5d 20 6d 61 79 20   statement] may 
29710 73 74 61 72 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  start.</dd>)^.**
29720 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
29730 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
29740 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
29750 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
29760 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
29770 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
29780 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
29790 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
297a0 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
297b0 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
297c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
297d0 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
297e0 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
297f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29800 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
29810 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
29820 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
29830 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
29840 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
29850 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
29860 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
29870 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
29880 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29890 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
298a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
298b0 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
298c0 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
298d0 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
298e0 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
298f0 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
29900 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
29910 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
29920 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
29930 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
29940 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c    10.#define SQL
29950 49 54 45 5f 4c 49 4d 49 54 5f 57 4f 52 4b 45 52  ITE_LIMIT_WORKER
29960 5f 54 48 52 45 41 44 53 20 20 20 20 20 20 20 20  _THREADS        
29970 20 20 20 31 31 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     11../*.** CAP
29980 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
29990 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
299a0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
299b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
299c0 6d 70 69 6c 65 72 7d 0a 2a 2a 20 4d 45 54 48 4f  mpiler}.** METHO
299d0 44 3a 20 73 71 6c 69 74 65 33 0a 2a 2a 20 43 4f  D: sqlite3.** CO
299e0 4e 53 54 52 55 43 54 4f 52 3a 20 73 71 6c 69 74  NSTRUCTOR: sqlit
299f0 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 54 6f  e3_stmt.**.** To
29a00 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
29a10 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
29a20 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
29a30 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
29a40 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
29a50 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
29a60 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
29a70 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
29a80 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
29a90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29aa0 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
29ab0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
29ac0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
29ad0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
29ae0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
29af0 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
29b00 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
29b10 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
29b20 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
29b30 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
29b40 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
29b50 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
29b60 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
29b70 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
29b80 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
29b90 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
29ba0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
29bb0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
29bc0 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
29bd0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
29be0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
29bf0 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
29c00 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
29c10 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
29c20 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
29c30 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
29c40 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
29c50 67 75 6d 65 6e 74 20 69 73 20 6e 65 67 61 74 69  gument is negati
29c60 76 65 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ve, then zSql is
29c70 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
29c80 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
29c90 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
29ca0 79 74 65 20 69 73 20 70 6f 73 69 74 69 76 65 2c  yte is positive,
29cb0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 0a   then it is the.
29cc0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  ** number of byt
29cd0 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
29ce0 6c 2e 20 20 5e 49 66 20 6e 42 79 74 65 20 69 73  l.  ^If nByte is
29cf0 20 7a 65 72 6f 2c 20 74 68 65 6e 20 6e 6f 20 70   zero, then no p
29d00 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65  repared.** state
29d10 6d 65 6e 74 20 69 73 20 67 65 6e 65 72 61 74 65  ment is generate
29d20 64 2e 0a 2a 2a 20 49 66 20 74 68 65 20 63 61 6c  d..** If the cal
29d30 6c 65 72 20 6b 6e 6f 77 73 20 74 68 61 74 20 74  ler knows that t
29d40 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
29d50 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
29d60 61 74 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 74 68  ated, then.** th
29d70 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 20 70  ere is a small p
29d80 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
29d90 74 61 67 65 20 74 6f 20 70 61 73 73 69 6e 67 20  tage to passing 
29da0 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
29db0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 74 68  er that.** is th
29dc0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
29dd0 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
29de0 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
29df0 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
29e00 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  l-terminator..**
29e10 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
29e20 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
29e30 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
29e40 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
29e50 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
29e60 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
29e70 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
29e80 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
29e90 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
29ea0 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
29eb0 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
29ec0 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
29ed0 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
29ee0 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
29ef0 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
29f00 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
29f10 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
29f20 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
29f30 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
29f40 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
29f50 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
29f60 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
29f70 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
29f80 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
29f90 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
29fa0 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
29fb0 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
29fc0 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
29fd0 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
29fe0 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
29ff0 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
2a000 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
2a010 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
2a020 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
2a030 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
2a040 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
2a050 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
2a060 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
2a070 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
2a080 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
2a090 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
2a0a0 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
2a0b0 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
2a0c0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
2a0d0 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
2a0e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2a0f0 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
2a100 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2a110 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
2a120 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
2a130 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
2a140 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2a150 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2a160 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
2a170 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
2a180 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
2a190 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
2a1a0 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
2a1b0 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
2a1c0 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
2a1d0 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
2a1e0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
2a1f0 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
2a200 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
2a210 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
2a220 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
2a230 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2a240 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
2a250 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
2a260 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
2a270 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
2a280 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
2a290 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
2a2a0 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
2a2b0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
2a2c0 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
2a2d0 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
2a2e0 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
2a2f0 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
2a300 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
2a310 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
2a320 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
2a330 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
2a340 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
2a350 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
2a360 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
2a370 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2a380 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
2a390 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
2a3a0 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
2a3b0 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
2a3c0 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61   it again. As ma
2a3d0 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41  ny as [SQLITE_MA
2a3e0 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a  X_SCHEMA_RETRY].
2a3f0 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20  ** retries will 
2a400 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c  occur before sql
2a410 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65  ite3_step() give
2a420 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73  s up and returns
2a430 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f   an error..** </
2a440 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
2a450 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
2a460 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
2a470 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
2a480 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
2a490 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
2a4a0 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
2a4b0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2a4c0 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
2a4d0 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
2a4e0 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
2a4f0 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
2a500 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
2a510 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
2a520 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
2a530 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
2a540 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
2a550 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
2a560 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
2a570 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
2a580 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
2a590 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
2a5a0 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
2a5b0 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
2a5c0 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
2a5d0 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
2a5e0 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
2a5f0 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
2a600 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
2a610 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
2a620 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
2a630 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
2a640 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
2a650 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
2a660 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
2a670 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
2a680 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
2a690 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
2a6a0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
2a6b0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
2a6c0 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
2a6d0 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
2a6e0 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
2a6f0 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
2a700 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
2a710 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
2a720 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
2a730 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
2a740 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
2a750 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
2a760 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
2a770 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
2a780 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
2a790 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
2a7a0 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
2a7b0 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
2a7c0 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
2a7d0 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
2a7e0 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
2a7f0 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
2a800 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2a810 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
2a820 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
2a830 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
2a840 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
2a850 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
2a860 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
2a870 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
2a880 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2a890 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT3] compile-t
2a8a0 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
2a8b0 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  abled..** </li>.
2a8c0 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
2a8d0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2a8e0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
2a8f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
2a900 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
2a910 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
2a920 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
2a930 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
2a940 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
2a950 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
2a960 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
2a970 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
2a980 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
2a990 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
2a9a0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
2a9b0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
2a9c0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
2a9d0 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
2a9e0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
2a9f0 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
2aa00 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
2aa10 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
2aa20 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
2aa30 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2aa40 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
2aa50 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
2aa60 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
2aa70 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
2aa80 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
2aa90 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
2aaa0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
2aab0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
2aac0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
2aad0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
2aae0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
2aaf0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
2ab00 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
2ab10 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
2ab20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
2ab30 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
2ab40 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
2ab50 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
2ab60 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
2ab70 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
2ab80 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
2ab90 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
2aba0 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
2abb0 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
2abc0 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
2abd0 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
2abe0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
2abf0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
2ac00 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
2ac10 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
2ac20 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
2ac30 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
2ac40 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
2ac50 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
2ac60 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
2ac70 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
2ac80 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
2ac90 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
2aca0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2acb0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
2acc0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
2acd0 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
2ace0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
2acf0 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
2ad00 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
2ad10 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2ad20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
2ad30 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
2ad40 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
2ad50 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
2ad60 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
2ad70 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
2ad80 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
2ad90 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
2ada0 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
2adb0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
2adc0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
2add0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
2ade0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
2adf0 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
2ae00 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
2ae10 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2ae20 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _stmt.**.** ^The
2ae30 20 73 71 6c 69 74 65 33 5f 73 71 6c 28 50 29 20   sqlite3_sql(P) 
2ae40 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2ae50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
2ae60 20 63 6f 70 79 20 6f 66 20 74 68 65 20 55 54 46   copy of the UTF
2ae70 2d 38 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  -8.** SQL text u
2ae80 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 5b 70  sed to create [p
2ae90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2aea0 74 5d 20 50 20 69 66 20 50 20 77 61 73 0a 2a 2a  t] P if P was.**
2aeb0 20 63 72 65 61 74 65 64 20 62 79 20 65 69 74 68   created by eith
2aec0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
2aed0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2aee0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2aef0 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  v2()]..** ^The s
2af00 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2af10 73 71 6c 28 50 29 20 69 6e 74 65 72 66 61 63 65  sql(P) interface
2af20 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2af30 65 72 20 74 6f 20 61 20 55 54 46 2d 38 0a 2a 2a  er to a UTF-8.**
2af40 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 69   string containi
2af50 6e 67 20 74 68 65 20 53 51 4c 20 74 65 78 74 20  ng the SQL text 
2af60 6f 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  of prepared stat
2af70 65 6d 65 6e 74 20 50 20 77 69 74 68 0a 2a 2a 20  ement P with.** 
2af80 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72  [bound parameter
2af90 73 5d 20 65 78 70 61 6e 64 65 64 2e 0a 2a 2a 0a  s] expanded..**.
2afa0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2afb0 2c 20 69 66 20 61 20 70 72 65 70 61 72 65 64 20  , if a prepared 
2afc0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 72 65  statement is cre
2afd0 61 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  ated using the S
2afe0 51 4c 0a 2a 2a 20 74 65 78 74 20 22 53 45 4c 45  QL.** text "SELE
2aff0 43 54 20 24 61 62 63 2c 3a 78 79 7a 22 20 61 6e  CT $abc,:xyz" an
2b000 64 20 69 66 20 70 61 72 61 6d 65 74 65 72 20 24  d if parameter $
2b010 61 62 63 20 69 73 20 62 6f 75 6e 64 20 74 6f 20  abc is bound to 
2b020 69 6e 74 65 67 65 72 20 32 33 34 35 0a 2a 2a 20  integer 2345.** 
2b030 61 6e 64 20 70 61 72 61 6d 65 74 65 72 20 3a 78  and parameter :x
2b040 79 7a 20 69 73 20 75 6e 62 6f 75 6e 64 2c 20 74  yz is unbound, t
2b050 68 65 6e 20 73 71 6c 69 74 65 33 5f 73 71 6c 28  hen sqlite3_sql(
2b060 29 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ) will return.**
2b070 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2b080 72 69 6e 67 2c 20 22 53 45 4c 45 43 54 20 24 61  ring, "SELECT $a
2b090 62 63 2c 3a 78 79 7a 22 20 62 75 74 20 73 71 6c  bc,:xyz" but sql
2b0a0 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71  ite3_expanded_sq
2b0b0 6c 28 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  l().** will retu
2b0c0 72 6e 20 22 53 45 4c 45 43 54 20 32 33 34 35 2c  rn "SELECT 2345,
2b0d0 4e 55 4c 4c 22 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  NULL".)^.**.** ^
2b0e0 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 70 61  The sqlite3_expa
2b0f0 6e 64 65 64 5f 73 71 6c 28 29 20 69 6e 74 65 72  nded_sql() inter
2b100 66 61 63 65 20 72 65 74 75 72 6e 73 20 4e 55 4c  face returns NUL
2b110 4c 20 69 66 20 69 6e 73 75 66 66 69 63 69 65 6e  L if insufficien
2b120 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 69 73 20 61  t memory.** is a
2b130 76 61 69 6c 61 62 6c 65 20 74 6f 20 68 6f 6c 64  vailable to hold
2b140 20 74 68 65 20 72 65 73 75 6c 74 2c 20 6f 72 20   the result, or 
2b150 69 66 20 74 68 65 20 72 65 73 75 6c 74 20 77 6f  if the result wo
2b160 75 6c 64 20 65 78 63 65 65 64 20 74 68 65 0a 2a  uld exceed the.*
2b170 2a 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 74  * the maximum st
2b180 72 69 6e 67 20 6c 65 6e 67 74 68 20 64 65 74 65  ring length dete
2b190 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 5b 53  rmined by the [S
2b1a0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
2b1b0 54 48 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  TH]..**.** ^The 
2b1c0 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
2b1d0 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
2b1e0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 6c 69  e-time option li
2b1f0 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f 66  mits the size of
2b200 0a 2a 2a 20 62 6f 75 6e 64 20 70 61 72 61 6d 65  .** bound parame
2b210 74 65 72 20 65 78 70 61 6e 73 69 6f 6e 73 2e 20  ter expansions. 
2b220 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d   ^The [SQLITE_OM
2b230 49 54 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69 6c  IT_TRACE] compil
2b240 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
2b250 20 63 61 75 73 65 73 20 73 71 6c 69 74 65 33 5f   causes sqlite3_
2b260 65 78 70 61 6e 64 65 64 5f 73 71 6c 28 29 20 74  expanded_sql() t
2b270 6f 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  o always return 
2b280 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
2b290 20 73 74 72 69 6e 67 20 72 65 74 75 72 6e 65 64   string returned
2b2a0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 71 6c 28   by sqlite3_sql(
2b2b0 50 29 20 69 73 20 6d 61 6e 61 67 65 64 20 62 79  P) is managed by
2b2c0 20 53 51 4c 69 74 65 20 61 6e 64 20 69 73 0a 2a   SQLite and is.*
2b2d0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
2b2e0 66 72 65 65 64 20 77 68 65 6e 20 74 68 65 20 70  freed when the p
2b2f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2b300 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 2e 0a  t is finalized..
2b310 2a 2a 20 5e 54 68 65 20 73 74 72 69 6e 67 20 72  ** ^The string r
2b320 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2b330 65 33 5f 65 78 70 61 6e 64 65 64 5f 73 71 6c 28  e3_expanded_sql(
2b340 50 29 2c 20 6f 6e 20 74 68 65 20 6f 74 68 65 72  P), on the other
2b350 20 68 61 6e 64 2c 0a 2a 2a 20 69 73 20 6f 62 74   hand,.** is obt
2b360 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2b370 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
2b380 64 20 6d 75 73 74 20 62 65 20 66 72 65 65 20 62  d must be free b
2b390 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
2b3a0 6e 0a 2a 2a 20 62 79 20 70 61 73 73 69 6e 67 20  n.** by passing 
2b3b0 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  it to [sqlite3_f
2b3c0 72 65 65 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  ree()]..*/.const
2b3d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
2b3e0 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ql(sqlite3_stmt 
2b3f0 2a 70 53 74 6d 74 29 3b 0a 63 68 61 72 20 2a 73  *pStmt);.char *s
2b400 71 6c 69 74 65 33 5f 65 78 70 61 6e 64 65 64 5f  qlite3_expanded_
2b410 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  sql(sqlite3_stmt
2b420 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2b430 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
2b440 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
2b450 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20  tatement Writes 
2b460 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 20  The Database.** 
2b470 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
2b480 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  stmt.**.** ^The 
2b490 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2b4a0 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
2b4b0 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
2b4c0 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
2b4d0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
2b4e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b4f0 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f  ment] X makes no
2b500 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20   direct changes 
2b510 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  to.** the conten
2b520 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
2b530 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  e file..**.** No
2b540 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61  te that [applica
2b550 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2b560 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a   functions] or.*
2b570 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
2b580 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  s] might change 
2b590 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64  the database ind
2b5a0 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64  irectly as a sid
2b5b0 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e  e effect.  .** ^
2b5c0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
2b5d0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
2b5e0 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69  defines a functi
2b5f0 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74  on "eval()" that
2b600 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69   .** calls [sqli
2b610 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65  te3_exec()], the
2b620 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
2b630 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
2b640 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  uld.** change th
2b650 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
2b660 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66  through side-eff
2b670 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  ects:.**.** <blo
2b680 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
2b690 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28      SELECT eval(
2b6a0 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27  'DELETE FROM t1'
2b6b0 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f  ) FROM t2;.** </
2b6c0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
2b6d0 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61  >.**.** But beca
2b6e0 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  use the [SELECT]
2b6f0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2b700 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  not change the d
2b710 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
2b720 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65  directly, sqlite
2b730 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2b740 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65  ) would still re
2b750 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a  turn true.)^.**.
2b760 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20  ** ^Transaction 
2b770 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e  control statemen
2b780 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49  ts such as [BEGI
2b790 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52  N], [COMMIT], [R
2b7a0 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41  OLLBACK],.** [SA
2b7b0 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52  VEPOINT], and [R
2b7c0 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71  ELEASE] cause sq
2b7d0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
2b7e0 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
2b7f0 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74  true,.** since t
2b800 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  he statements th
2b810 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20  emselves do not 
2b820 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20  actually modify 
2b830 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
2b840 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20  .** rather they 
2b850 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69  control the timi
2b860 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72  ng of when other
2b870 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69   statements modi
2b880 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62  fy the .** datab
2b890 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41  ase.  ^The [ATTA
2b8a0 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d  CH] and [DETACH]
2b8b0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f   statements also
2b8c0 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65   cause.** sqlite
2b8d0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2b8e0 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2b8f0 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68   since, while th
2b900 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  ose statements.*
2b910 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e  * change the con
2b920 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  figuration of a 
2b930 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2b940 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  ion, they do not
2b950 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65   make .** change
2b960 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74  s to the content
2b970 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2b980 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a   files on disk..
2b990 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b9a0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2b9b0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2b9c0 73 20 74 72 75 65 20 66 6f 72 20 5b 42 45 47 49  s true for [BEGI
2b9d0 4e 5d 20 73 69 6e 63 65 0a 2a 2a 20 5b 42 45 47  N] since.** [BEG
2b9e0 49 4e 5d 20 6d 65 72 65 6c 79 20 73 65 74 73 20  IN] merely sets 
2b9f0 69 6e 74 65 72 6e 61 6c 20 66 6c 61 67 73 2c 20  internal flags, 
2ba00 62 75 74 20 74 68 65 20 5b 42 45 47 49 4e 7c 42  but the [BEGIN|B
2ba10 45 47 49 4e 20 49 4d 4d 45 44 49 41 54 45 5d 20  EGIN IMMEDIATE] 
2ba20 61 6e 64 0a 2a 2a 20 5b 42 45 47 49 4e 7c 42 45  and.** [BEGIN|BE
2ba30 47 49 4e 20 45 58 43 4c 55 53 49 56 45 5d 20 63  GIN EXCLUSIVE] c
2ba40 6f 6d 6d 61 6e 64 73 20 64 6f 20 74 6f 75 63 68  ommands do touch
2ba50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
2ba60 64 20 73 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  d so.** sqlite3_
2ba70 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
2ba80 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 66 6f  returns false fo
2ba90 72 20 74 68 6f 73 65 20 63 6f 6d 6d 61 6e 64 73  r those commands
2baa0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2bab0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73  _stmt_readonly(s
2bac0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2bad0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2bae0 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
2baf0 49 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  If A Prepared St
2bb00 61 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e  atement Has Been
2bb10 20 52 65 73 65 74 0a 2a 2a 20 4d 45 54 48 4f 44   Reset.** METHOD
2bb20 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a  : sqlite3_stmt.*
2bb30 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2bb40 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69  3_stmt_busy(S) i
2bb50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2bb60 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
2bb70 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   if the.** [prep
2bb80 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2bb90 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70  S has been stepp
2bba0 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65  ed at least once
2bbb0 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2bbc0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74  te3_step(S)] but
2bbd0 20 68 61 73 20 6e 65 69 74 68 65 72 20 72 75 6e   has neither run
2bbe0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 28   to completion (
2bbf0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c  returned.** [SQL
2bc00 49 54 45 5f 44 4f 4e 45 5d 20 66 72 6f 6d 20 5b  ITE_DONE] from [
2bc10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2bc20 29 20 6e 6f 72 0a 2a 2a 20 62 65 65 6e 20 72 65  ) nor.** been re
2bc30 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  set using [sqlit
2bc40 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e  e3_reset(S)].  ^
2bc50 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
2bc60 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65  _busy(S).** inte
2bc70 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61  rface returns fa
2bc80 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55  lse if S is a NU
2bc90 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
2bca0 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e  S is not a .** N
2bcb0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ULL pointer and 
2bcc0 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72  is not a pointer
2bcd0 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65   to a valid [pre
2bce0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2bcf0 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e  .** object, then
2bd00 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
2bd10 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
2bd20 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
2bd30 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ble..**.** This 
2bd40 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
2bd50 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61   used in combina
2bd60 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65  tion [sqlite3_ne
2bd70 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f  xt_stmt()].** to
2bd80 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70   locate all prep
2bd90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
2bda0 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
2bdb0 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63  a database .** c
2bdc0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61  onnection that a
2bdd0 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65  re in need of be
2bde0 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73  ing reset.  This
2bdf0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a   can be used,.**
2be00 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e   for example, in
2be10 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74   diagnostic rout
2be20 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66  ines to search f
2be30 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20  or prepared .** 
2be40 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
2be50 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72  are holding a tr
2be60 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a  ansaction open..
2be70 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
2be80 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33  tmt_busy(sqlite3
2be90 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2bea0 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69  CAPI3REF: Dynami
2beb0 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75  cally Typed Valu
2bec0 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57  e Object.** KEYW
2bed0 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64  ORDS: {protected
2bee0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20   sqlite3_value} 
2bef0 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  {unprotected sql
2bf00 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a  ite3_value}.**.*
2bf10 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68  * SQLite uses th
2bf20 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2bf30 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73  object to repres
2bf40 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a  ent all values.*
2bf50 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74  * that can be st
2bf60 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61  ored in a databa
2bf70 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65  se table. SQLite
2bf80 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79   uses dynamic ty
2bf90 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ping.** for the 
2bfa0 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73  values it stores
2bfb0 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65  .  ^Values store
2bfc0 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c  d in sqlite3_val
2bfd0 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61  ue objects.** ca
2bfe0 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66  n be integers, f
2bff0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
2c000 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42  lues, strings, B
2c010 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a  LOBs, or NULL..*
2c020 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f  *.** An sqlite3_
2c030 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79  value object may
2c040 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74   be either "prot
2c050 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f  ected" or "unpro
2c060 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65  tected"..** Some
2c070 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75   interfaces requ
2c080 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20  ire a protected 
2c090 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2c0a0 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73  Other interfaces
2c0b0 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20  .** will accept 
2c0c0 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74  either a protect
2c0d0 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  ed or an unprote
2c0e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2c0f0 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74  ue..** Every int
2c100 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65  erface that acce
2c110 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  pts sqlite3_valu
2c120 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63  e arguments spec
2c130 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72  ifies.** whether
2c140 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69   or not it requi
2c150 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20  res a protected 
2c160 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20  sqlite3_value.  
2c170 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
2c180 76 61 6c 75 65 5f 64 75 70 28 29 5d 20 69 6e 74  value_dup()] int
2c190 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2c1a0 65 64 20 74 6f 20 63 6f 6e 73 74 72 75 63 74 20  ed to construct 
2c1b0 61 20 6e 65 77 20 0a 2a 2a 20 70 72 6f 74 65 63  a new .** protec
2c1c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c1d0 65 20 66 72 6f 6d 20 61 6e 20 75 6e 70 72 6f 74  e from an unprot
2c1e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2c1f0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
2c200 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
2c210 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
2c220 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
2c230 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
2c240 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
2c250 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
2c260 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
2c270 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2c280 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c290 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
2c2a0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
2c2b0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
2c2c0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2c2d0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
2c2e0 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
2c2f0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
2c300 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
2c310 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
2c320 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
2c330 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
2c340 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
2c350 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
2c360 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
2c370 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
2c380 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
2c390 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
2c3a0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
2c3b0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
2c3c0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
2c3d0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
2c3e0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
2c3f0 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
2c400 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
2c410 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
2c420 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
2c430 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
2c440 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
2c450 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
2c460 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
2c470 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
2c480 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
2c490 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
2c4a0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
2c4b0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
2c4c0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
2c4d0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2c4e0 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
2c4f0 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
2c500 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
2c510 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
2c520 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
2c530 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
2c540 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
2c550 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
2c560 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
2c570 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2c580 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
2c590 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
2c5a0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
2c5b0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
2c5c0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
2c5d0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
2c5e0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
2c5f0 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
2c600 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2c610 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
2c620 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
2c630 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2c640 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
2c650 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
2c660 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
2c670 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
2c680 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2c690 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
2c6a0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
2c6b0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
2c6c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2c6d0 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
2c6e0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
2c6f0 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
2c700 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
2c710 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
2c720 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
2c730 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
2c740 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
2c750 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
2c760 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
2c770 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2c780 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
2c790 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
2c7a0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
2c7b0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
2c7c0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
2c7d0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
2c7e0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2c7f0 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
2c800 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2c810 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
2c820 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
2c830 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
2c840 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
2c850 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
2c860 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
2c870 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
2c880 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2c890 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2c8a0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
2c8b0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
2c8c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2c8d0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
2c8e0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
2c8f0 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
2c900 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
2c910 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
2c920 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2c930 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
2c940 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
2c950 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c960 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
2c970 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
2c980 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
2c990 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
2c9a0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
2c9b0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
2c9c0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
2c9d0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
2c9e0 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
2c9f0 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
2ca00 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
2ca10 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
2ca20 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  _stmt.**.** ^(In
2ca30 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2ca40 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f  nt text input to
2ca50 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ca60 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20  e_v2()] and its 
2ca70 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74  variants,.** lit
2ca80 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70  erals may be rep
2ca90 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72 61  laced by a [para
2caa0 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63  meter] that matc
2cab0 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f  hes one of follo
2cac0 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65  wing.** template
2cad0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2cae0 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e   <li>  ?.** <li>
2caf0 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20    ?NNN.** <li>  
2cb00 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56  :VVV.** <li>  @V
2cb10 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56  VV.** <li>  $VVV
2cb20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2cb30 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73  In the templates
2cb40 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72   above, NNN repr
2cb50 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65  esents an intege
2cb60 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e  r literal,.** an
2cb70 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74 73  d VVV represents
2cb80 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63   an alphanumeric
2cb90 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20   identifier.)^  
2cba0 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74  ^The values of t
2cbb0 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hese.** paramete
2cbc0 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20  rs (also called 
2cbd0 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20  "host parameter 
2cbe0 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70  names" or "SQL p
2cbf0 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63  arameters").** c
2cc00 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67 20  an be set using 
2cc10 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
2cc20 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65  _*() routines de
2cc30 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a  fined here..**.*
2cc40 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2cc50 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
2cc60 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2cc70 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73  utines is always
2cc80 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
2cc90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
2cca0 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  mt] object retur
2ccb0 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c  ned from.** [sql
2ccc0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2ccd0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
2cce0 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ts..**.** ^The s
2ccf0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2cd00 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2cd10 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  he SQL parameter
2cd20 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e   to be set..** ^
2cd30 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c  The leftmost SQL
2cd40 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61   parameter has a
2cd50 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e  n index of 1.  ^
2cd60 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61  When the same na
2cd70 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d  med.** SQL param
2cd80 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72  eter is used mor
2cd90 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63  e than once, sec
2cda0 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
2cdb0 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65  nt.** occurrence
2cdc0 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20  s have the same 
2cdd0 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69 72  index as the fir
2cde0 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a  st occurrence..*
2cdf0 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72  * ^The index for
2ce00 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
2ce10 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20  s can be looked 
2ce20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  up using the.** 
2ce30 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2ce40 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2ce50 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64 2e   API if desired.
2ce60 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20    ^The index.** 
2ce70 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d  for "?NNN" param
2ce80 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61 6c  eters is the val
2ce90 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54  ue of NNN..** ^T
2cea0 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73  he NNN value mus
2ceb0 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20 61  t be between 1 a
2cec0 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  nd the [sqlite3_
2ced0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61  limit()].** para
2cee0 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49  meter [SQLITE_LI
2cef0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
2cf00 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61  BER] (default va
2cf10 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a  lue: 999)..**.**
2cf20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
2cf30 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75  ment is the valu
2cf40 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65  e to bind to the
2cf50 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
2cf60 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
2cf70 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
2cf80 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72  3_bind_text() or
2cf90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2cfa0 78 74 31 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  xt16().** or sql
2cfb0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
2cfc0 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
2cfd0 65 72 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  er then the four
2cfe0 74 68 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  th parameter.** 
2cff0 69 73 20 69 67 6e 6f 72 65 64 20 61 6e 64 20 74  is ignored and t
2d000 68 65 20 65 6e 64 20 72 65 73 75 6c 74 20 69 73  he end result is
2d010 20 74 68 65 20 73 61 6d 65 20 61 73 20 73 71 6c   the same as sql
2d020 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29  ite3_bind_null()
2d030 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
2d040 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
2d050 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
2d060 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
2d070 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
2d080 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2d090 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
2d0a0 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
2d0b0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
2d0c0 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
2d0d0 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
2d0e0 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
2d0f0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2d100 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
2d110 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2d120 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
2d130 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  d_text() or sqli
2d140 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2d150 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  ).** is negative
2d160 2c 20 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74  , then the lengt
2d170 68 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20  h of the string 
2d180 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  is.** the number
2d190 20 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20   of bytes up to 
2d1a0 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74  the first zero t
2d1b0 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66  erminator..** If
2d1c0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
2d1d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2d1e0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20  _bind_blob() is 
2d1f0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a  negative, then.*
2d200 2a 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  * the behavior i
2d210 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
2d220 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  If a non-negativ
2d230 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2d240 65 72 20 69 73 20 70 72 6f 76 69 64 65 64 20 74  er is provided t
2d250 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2d260 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ext().** or sqli
2d270 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
2d280 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  ) or sqlite3_bin
2d290 64 5f 74 65 78 74 36 34 28 29 20 74 68 65 6e 0a  d_text64() then.
2d2a0 2a 2a 20 74 68 61 74 20 70 61 72 61 6d 65 74 65  ** that paramete
2d2b0 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  r must be the by
2d2c0 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65  te offset.** whe
2d2d0 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69  re the NUL termi
2d2e0 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75  nator would occu
2d2f0 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73  r assuming the s
2d300 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a  tring were NUL.*
2d310 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  * terminated.  I
2d320 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
2d330 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79  ters occur at by
2d340 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20  te offsets less 
2d350 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c  than .** the val
2d360 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68  ue of the fourth
2d370 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20   parameter then 
2d380 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
2d390 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a  ring value will.
2d3a0 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ** contain embed
2d3b0 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72  ded NULs.  The r
2d3c0 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73  esult of express
2d3d0 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73  ions involving s
2d3e0 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65  trings.** with e
2d3f0 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20  mbedded NULs is 
2d400 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
2d410 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
2d420 6d 65 6e 74 20 74 6f 20 74 68 65 20 42 4c 4f 42  ment to the BLOB
2d430 20 61 6e 64 20 73 74 72 69 6e 67 20 62 69 6e 64   and string bind
2d440 69 6e 67 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ing interfaces.*
2d450 2a 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f  * is a destructo
2d460 72 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73  r used to dispos
2d470 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
2d480 0a 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72  .** string after
2d490 20 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69   SQLite has fini
2d4a0 73 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e  shed with it.  ^
2d4b0 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2d4c0 73 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64  s called.** to d
2d4d0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
2d4e0 4f 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65  OB or string eve
2d4f0 6e 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  n if the call to
2d500 20 62 69 6e 64 20 41 50 49 20 66 61 69 6c 73 2e   bind API fails.
2d510 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
2d520 68 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a  h argument is.**
2d530 20 74 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c   the special val
2d540 75 65 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49  ue [SQLITE_STATI
2d550 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  C], then SQLite 
2d560 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65  assumes that the
2d570 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
2d580 69 73 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e  is in static, un
2d590 6d 61 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e  managed space an
2d5a0 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  d does not need 
2d5b0 74 6f 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20  to be freed..** 
2d5c0 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72  ^If the fifth ar
2d5d0 67 75 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76  gument has the v
2d5e0 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41  alue [SQLITE_TRA
2d5f0 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a  NSIENT], then.**
2d600 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74   SQLite makes it
2d610 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
2d620 70 79 20 6f 66 20 74 68 65 20 64 61 74 61 20 69  py of the data i
2d630 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f  mmediately, befo
2d640 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65  re.** the sqlite
2d650 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
2d660 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ne returns..**.*
2d670 2a 20 5e 54 68 65 20 73 69 78 74 68 20 61 72 67  * ^The sixth arg
2d680 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2d690 5f 62 69 6e 64 5f 74 65 78 74 36 34 28 29 20 6d  _bind_text64() m
2d6a0 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 0a 2a 2a  ust be one of.**
2d6b0 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20   [SQLITE_UTF8], 
2d6c0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
2d6d0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
2d6e0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46  , or [SQLITE_UTF
2d6f0 31 36 4c 45 5d 0a 2a 2a 20 74 6f 20 73 70 65 63  16LE].** to spec
2d700 69 66 79 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ify the encoding
2d710 20 6f 66 20 74 68 65 20 74 65 78 74 20 69 6e 20   of the text in 
2d720 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
2d730 74 65 72 2e 20 20 49 66 0a 2a 2a 20 74 68 65 20  ter.  If.** the 
2d740 73 69 78 74 68 20 61 72 67 75 6d 65 6e 74 20 74  sixth argument t
2d750 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2d760 65 78 74 36 34 28 29 20 69 73 20 6e 6f 74 20 6f  ext64() is not o
2d770 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 61 6c 6c  ne of the.** all
2d780 6f 77 65 64 20 76 61 6c 75 65 73 20 73 68 6f 77  owed values show
2d790 6e 20 61 62 6f 76 65 2c 20 6f 72 20 69 66 20 74  n above, or if t
2d7a0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
2d7b0 20 69 73 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a   is different.**
2d7c0 20 66 72 6f 6d 20 74 68 65 20 65 6e 63 6f 64 69   from the encodi
2d7d0 6e 67 20 73 70 65 63 69 66 69 65 64 20 62 79 20  ng specified by 
2d7e0 74 68 65 20 73 69 78 74 68 20 70 61 72 61 6d 65  the sixth parame
2d7f0 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ter, then the be
2d800 68 61 76 69 6f 72 0a 2a 2a 20 69 73 20 75 6e 64  havior.** is und
2d810 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2d820 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2d830 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69  zeroblob() routi
2d840 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20  ne binds a BLOB 
2d850 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74  of length N that
2d860 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69  .** is filled wi
2d870 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a  th zeroes.  ^A z
2d880 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66  eroblob uses a f
2d890 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d  ixed amount of m
2d8a0 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61  emory.** (just a
2d8b0 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c  n integer to hol
2d8c0 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c  d its size) whil
2d8d0 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72  e it is being pr
2d8e0 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f  ocessed..** Zero
2d8f0 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64  blobs are intend
2d900 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70  ed to serve as p
2d910 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2d920 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63  BLOBs whose.** c
2d930 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20  ontent is later 
2d940 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a  written using.**
2d950 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f   [sqlite3_blob_o
2d960 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61  pen | incrementa
2d970 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74  l BLOB I/O] rout
2d980 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61  ines..** ^A nega
2d990 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74  tive value for t
2d9a0 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75  he zeroblob resu
2d9b0 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65  lts in a zero-le
2d9c0 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a  ngth BLOB..**.**
2d9d0 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20   ^If any of the 
2d9e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2d9f0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2da00 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
2da10 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20   pointer.** for 
2da20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2da30 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68  atement] or with
2da40 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2da50 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a  ement for which.
2da60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
2da70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c  ()] has been cal
2da80 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c  led more recentl
2da90 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f  y than [sqlite3_
2daa0 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65  reset()],.** the
2dab0 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20  n the call will 
2dac0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d  return [SQLITE_M
2dad0 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20  ISUSE].  If any 
2dae0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a  sqlite3_bind_().
2daf0 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61  ** routine is pa
2db00 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64  ssed a [prepared
2db10 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
2db20 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2db30 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75  zed, the.** resu
2db40 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  lt is undefined 
2db50 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72  and probably har
2db60 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e  mful..**.** ^Bin
2db70 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c  dings are not cl
2db80 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71  eared by the [sq
2db90 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72  lite3_reset()] r
2dba0 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f  outine..** ^Unbo
2dbb0 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61  und parameters a
2dbc0 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  re interpreted a
2dbd0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
2dbe0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2dbf0 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  * routines retur
2dc00 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  n [SQLITE_OK] on
2dc10 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a   success or an.*
2dc20 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  * [error code] i
2dc30 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20  f anything goes 
2dc40 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49  wrong..** ^[SQLI
2dc50 54 45 5f 54 4f 4f 42 49 47 5d 20 6d 69 67 68 74  TE_TOOBIG] might
2dc60 20 62 65 20 72 65 74 75 72 6e 65 64 20 69 66 20   be returned if 
2dc70 74 68 65 20 73 69 7a 65 20 6f 66 20 61 20 73 74  the size of a st
2dc80 72 69 6e 67 20 6f 72 20 42 4c 4f 42 0a 2a 2a 20  ring or BLOB.** 
2dc90 65 78 63 65 65 64 73 20 6c 69 6d 69 74 73 20 69  exceeds limits i
2dca0 6d 70 6f 73 65 64 20 62 79 20 5b 73 71 6c 69 74  mposed by [sqlit
2dcb0 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
2dcc0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 29  E_LIMIT_LENGTH])
2dcd0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d   or.** [SQLITE_M
2dce0 41 58 5f 4c 45 4e 47 54 48 5d 2e 0a 2a 2a 20 5e  AX_LENGTH]..** ^
2dcf0 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69  [SQLITE_RANGE] i
2dd00 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 74 68  s returned if th
2dd10 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69  e parameter.** i
2dd20 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2dd30 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f  ange.  ^[SQLITE_
2dd40 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75 72 6e  NOMEM] is return
2dd50 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66  ed if malloc() f
2dd60 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ails..**.** See 
2dd70 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2dd80 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2dd90 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  unt()],.** [sqli
2dda0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2ddb0 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20  er_name()], and 
2ddc0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2ddd0 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2dde0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2ddf0 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74  _bind_blob(sqlit
2de00 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
2de10 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20  onst void*, int 
2de20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
2de30 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
2de40 62 69 6e 64 5f 62 6c 6f 62 36 34 28 73 71 6c 69  bind_blob64(sqli
2de50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2de60 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 73 71 6c  const void*, sql
2de70 69 74 65 33 5f 75 69 6e 74 36 34 2c 0a 20 20 20  ite3_uint64,.   
2de80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2de90 20 20 20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69       void(*)(voi
2dea0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
2deb0 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
2dec0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ded0 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20 73  , double);.int s
2dee0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 28  qlite3_bind_int(
2def0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2df00 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  nt, int);.int sq
2df10 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
2df20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2df30 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
2df40 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  64);.int sqlite3
2df50 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74  _bind_null(sqlit
2df60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2df70 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2df80 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74  _text(sqlite3_st
2df90 6d 74 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  mt*,int,const ch
2dfa0 61 72 2a 2c 69 6e 74 2c 76 6f 69 64 28 2a 29 28  ar*,int,void(*)(
2dfb0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
2dfc0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
2dfd0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2dfe0 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
2dff0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
2e000 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
2e010 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 36 34 28  te3_bind_text64(
2e020 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2e030 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
2e040 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 2c   sqlite3_uint64,
2e050 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
2e060 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 28 2a            void(*
2e070 29 28 76 6f 69 64 2a 29 2c 20 75 6e 73 69 67 6e  )(void*), unsign
2e080 65 64 20 63 68 61 72 20 65 6e 63 6f 64 69 6e 67  ed char encoding
2e090 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
2e0a0 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
2e0b0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2e0c0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
2e0d0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
2e0e0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
2e0f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2e100 74 2c 20 69 6e 74 20 6e 29 3b 0a 69 6e 74 20 73  t, int n);.int s
2e110 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2e120 62 6c 6f 62 36 34 28 73 71 6c 69 74 65 33 5f 73  blob64(sqlite3_s
2e130 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
2e140 65 33 5f 75 69 6e 74 36 34 29 3b 0a 0a 2f 2a 0a  e3_uint64);../*.
2e150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
2e160 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
2e170 65 74 65 72 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a  eters.** METHOD:
2e180 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2e190 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
2e1a0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2e1b0 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
2e1c0 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
2e1d0 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
2e1e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e1f0 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
2e200 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
2e210 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
2e220 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
2e230 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
2e240 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
2e250 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
2e260 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
2e270 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
2e280 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
2e290 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
2e2a0 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
2e2b0 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
2e2c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
2e2d0 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
2e2e0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
2e2f0 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
2e300 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
2e310 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
2e320 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
2e330 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
2e340 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
2e350 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
2e360 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
2e370 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
2e380 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
2e390 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
2e3a0 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
2e3b0 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
2e3c0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2e3d0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2e3e0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2e3f0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e400 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2e410 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2e420 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2e430 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ex()]..*/.int sq
2e440 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e450 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
2e460 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2e470 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
2e480 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
2e490 65 74 65 72 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  eter.** METHOD: 
2e4a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a  sqlite3_stmt.**.
2e4b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2e4c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2e4d0 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
2e4e0 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
2e4f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
2e500 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
2e510 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
2e520 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
2e530 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
2e540 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
2e550 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
2e560 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2e570 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
2e580 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
2e590 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
2e5a0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2e5b0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2e5c0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
2e5d0 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
2e5e0 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
2e5f0 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
2e600 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
2e610 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
2e620 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
2e630 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
2e640 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
2e650 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
2e660 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
2e670 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
2e680 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
2e690 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
2e6a0 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
2e6b0 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
2e6c0 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
2e6d0 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
2e6e0 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
2e6f0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
2e700 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
2e710 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
2e720 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
2e730 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
2e740 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
2e750 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
2e760 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
2e770 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
2e780 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
2e790 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
2e7a0 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
2e7b0 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
2e7c0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
2e7d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2e7e0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
2e7f0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2e800 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
2e810 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2e820 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2e830 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2e840 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2e850 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
2e860 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2e870 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2e880 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
2e890 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
2e8a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
2e8b0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2e8c0 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
2e8d0 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
2e8e0 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
2e8f0 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
2e900 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2e910 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 52  e3_stmt.**.** ^R
2e920 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
2e930 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
2e940 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
2e950 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
2e960 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
2e970 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
2e980 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
2e990 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
2e9a0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
2e9b0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2e9c0 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
2e9d0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2e9e0 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
2e9f0 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
2ea00 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
2ea10 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
2ea20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
2ea30 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
2ea40 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
2ea50 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
2ea60 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
2ea70 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2ea80 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2ea90 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2eaa0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2eab0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2eac0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2ead0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2eae0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2eaf0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2eb00 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2eb10 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2eb20 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2eb30 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73  _index(sqlite3_s
2eb40 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  tmt*, const char
2eb50 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a   *zName);../*.**
2eb60 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74   CAPI3REF: Reset
2eb70 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e   All Bindings On
2eb80 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
2eb90 65 6d 65 6e 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  ement.** METHOD:
2eba0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2ebb0 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
2ebc0 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
2ebd0 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
2ebe0 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
2ebf0 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
2ec00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2ec10 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
2ec20 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2ec30 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
2ec40 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
2ec50 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
2ec60 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
2ec70 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
2ec80 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2ec90 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2eca0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ecb0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
2ecc0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
2ecd0 74 20 53 65 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a  t Set.** METHOD:
2ece0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a   sqlite3_stmt.**
2ecf0 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2ed00 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
2ed10 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
2ed20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  set returned by 
2ed30 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2ed40 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e 49 66   statement]. ^If
2ed50 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
2ed60 74 75 72 6e 73 20 30 2c 20 74 68 61 74 20 6d 65  turns 0, that me
2ed70 61 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 70 72 65  ans the .** [pre
2ed80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ed90 20 72 65 74 75 72 6e 73 20 6e 6f 20 64 61 74 61   returns no data
2eda0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
2edb0 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 20 5e   [UPDATE])..** ^
2edc0 48 6f 77 65 76 65 72 2c 20 6a 75 73 74 20 62 65  However, just be
2edd0 63 61 75 73 65 20 74 68 69 73 20 72 6f 75 74 69  cause this routi
2ede0 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 73  ne returns a pos
2edf0 69 74 69 76 65 20 6e 75 6d 62 65 72 20 64 6f 65  itive number doe
2ee00 73 20 6e 6f 74 0a 2a 2a 20 6d 65 61 6e 20 74 68  s not.** mean th
2ee10 61 74 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 72  at one or more r
2ee20 6f 77 73 20 6f 66 20 64 61 74 61 20 77 69 6c 6c  ows of data will
2ee30 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   be returned.  ^
2ee40 41 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  A SELECT stateme
2ee50 6e 74 0a 2a 2a 20 77 69 6c 6c 20 61 6c 77 61 79  nt.** will alway
2ee60 73 20 68 61 76 65 20 61 20 70 6f 73 69 74 69 76  s have a positiv
2ee70 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2ee80 5f 63 6f 75 6e 74 28 29 20 62 75 74 20 64 65 70  _count() but dep
2ee90 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 0a 2a 2a  ending on the.**
2eea0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
2eeb0 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
2eec0 65 20 74 61 62 6c 65 20 63 6f 6e 74 65 6e 74 2c  e table content,
2eed0 20 69 74 20 6d 69 67 68 74 20 72 65 74 75 72 6e   it might return
2eee0 20 6e 6f 20 72 6f 77 73 2e 0a 2a 2a 0a 2a 2a 20   no rows..**.** 
2eef0 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2ef00 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d  e3_data_count()]
2ef10 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2ef20 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c  column_count(sql
2ef30 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2ef40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ef50 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73  EF: Column Names
2ef60 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74   In A Result Set
2ef70 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
2ef80 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e  te3_stmt.**.** ^
2ef90 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2efa0 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
2efb0 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
2efc0 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
2efd0 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
2efe0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2eff0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
2f000 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2f010 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
2f020 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2f030 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2f040 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2f050 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
2f060 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f070 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
2f080 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2f090 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
2f0a0 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
2f0b0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
2f0c0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2f0d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f0e0 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
2f0f0 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
2f100 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
2f110 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2f120 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
2f130 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
2f140 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2f150 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
2f160 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
2f170 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
2f180 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
2f190 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
2f1a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2f1b0 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
2f1c0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
2f1d0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2f1e0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2f1f0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2f200 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2f210 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2f220 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2f230 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2f240 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2f250 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
2f260 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2f270 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2f280 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2f290 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
2f2a0 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
2f2b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
2f2c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
2f2d0 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
2f2e0 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
2f2f0 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
2f300 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
2f310 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
2f320 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
2f330 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
2f340 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2f350 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2f360 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
2f370 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
2f380 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
2f390 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
2f3a0 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
2f3b0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
2f3c0 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
2f3d0 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
2f3e0 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
2f3f0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
2f400 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
2f410 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
2f420 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
2f430 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
2f440 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f   the next..*/.co
2f450 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2f460 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
2f470 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f480 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
2f490 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2f4a0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2f4b0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
2f4c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2f4d0 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
2f4e0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2f4f0 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74  ** METHOD: sqlit
2f500 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 54  e3_stmt.**.** ^T
2f510 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72  hese routines pr
2f520 6f 76 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f  ovide a means to
2f530 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
2f540 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2f550 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c  and.** table col
2f560 75 6d 6e 20 74 68 61 74 20 69 73 20 74 68 65 20  umn that is the 
2f570 6f 72 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74  origin of a part
2f580 69 63 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f  icular result co
2f590 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45  lumn in.** [SELE
2f5a0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  CT] statement..*
2f5b0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
2f5c0 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 20 74  he database or t
2f5d0 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63  able or column c
2f5e0 61 6e 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  an be returned a
2f5f0 73 0a 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54  s.** either a UT
2f600 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74  F-8 or UTF-16 st
2f610 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74  ring.  ^The _dat
2f620 61 62 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20  abase_ routines 
2f630 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61  return.** the da
2f640 74 61 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65  tabase name, the
2f650 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65   _table_ routine
2f660 73 20 72 65 74 75 72 6e 20 74 68 65 20 74 61 62  s return the tab
2f670 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20  le name, and.** 
2f680 74 68 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74  the origin_ rout
2f690 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2f6a0 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20  column name..** 
2f6b0 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
2f6c0 72 69 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e  ring is valid un
2f6d0 74 69 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65  til the [prepare
2f6e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20  d statement] is 
2f6f0 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69  destroyed.** usi
2f700 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
2f710 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
2f720 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2f730 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
2f740 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
2f750 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
2f760 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
2f770 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
2f780 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
2f790 6e 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e  ntil the same in
2f7a0 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71  formation is req
2f7b0 75 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20  uested.** again 
2f7c0 69 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65  in a different e
2f7d0 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  ncoding..**.** ^
2f7e0 54 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e  The names return
2f7f0 65 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69  ed are the origi
2f800 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e  nal un-aliased n
2f810 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64  ames of the.** d
2f820 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20  atabase, table, 
2f830 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  and column..**.*
2f840 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
2f850 75 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69  ument to these i
2f860 6e 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b  nterfaces is a [
2f870 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2f880 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66  nt]..** ^These f
2f890 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
2f8a0 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
2f8b0 74 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74  t the Nth result
2f8c0 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64   column returned
2f8d0 20 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   by.** the state
2f8e0 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73  ment, where N is
2f8f0 20 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63   the second func
2f900 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  tion argument..*
2f910 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74  * ^The left-most
2f920 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d   column is colum
2f930 6e 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f  n 0 for these ro
2f940 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  utines..**.** ^I
2f950 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  f the Nth column
2f960 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2f970 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e   statement is an
2f980 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a   expression or.*
2f990 2a 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69  * subquery and i
2f9a0 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76  s not a column v
2f9b0 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f  alue, then all o
2f9c0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
2f9d0 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c  s return.** NULL
2f9e0 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
2f9f0 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74  e might also ret
2fa00 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65  urn NULL if a me
2fa10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2fa20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e  error.** occurs.
2fa30 20 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68    ^Otherwise, th
2fa40 65 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61  ey return the na
2fa50 6d 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68  me of the attach
2fa60 65 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62  ed database, tab
2fa70 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e  le,.** or column
2fa80 20 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75   that query resu
2fa90 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78  lt column was ex
2faa0 74 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a  tracted from..**
2fab0 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c  .** ^As with all
2fac0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50   other SQLite AP
2fad0 49 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20  Is, those whose 
2fae0 6e 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22  names end with "
2faf0 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54  16" return.** UT
2fb00 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72  F-16 encoded str
2fb10 69 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68  ings and the oth
2fb20 65 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  er functions ret
2fb30 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a  urn UTF-8..**.**
2fb40 20 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65   ^These APIs are
2fb50 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20   only available 
2fb60 69 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77  if the library w
2fb70 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
2fb80 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2fb90 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45  ENABLE_COLUMN_ME
2fba0 54 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f  TADATA] C-prepro
2fbb0 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a  cessor symbol..*
2fbc0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2fbd0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2fbe0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20   one or more of 
2fbf0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
2fc00 67 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a  gainst the same.
2fc10 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
2fc20 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e  ement and column
2fc30 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2fc40 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2fc50 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69  ts are.** undefi
2fc60 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77  ned..**.** If tw
2fc70 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64  o or more thread
2fc80 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f  s call one or mo
2fc90 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  re.** [sqlite3_c
2fca0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2fcb0 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74  ame | column met
2fcc0 61 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73  adata interfaces
2fcd0 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d  ].** for the sam
2fce0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2fcf0 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c  ement] and resul
2fd00 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74  t column.** at t
2fd10 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
2fd20 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
2fd30 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  e undefined..*/.
2fd40 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2fd50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2fd60 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
2fd70 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2fd80 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2fd90 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2fda0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2fdb0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2fdc0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2fdd0 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
2fde0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2fdf0 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
2fe00 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2fe10 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71  _table_name16(sq
2fe20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2fe30 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
2fe40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2fe50 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
2fe60 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
2fe70 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2fe80 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2fe90 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2fea0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2feb0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
2fec0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
2fed0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2fee0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
2fef0 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  3_stmt.**.** ^(T
2ff00 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2ff10 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
2ff20 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2ff30 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
2ff40 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
2ff50 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2ff60 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2ff70 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
2ff80 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
2ff90 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
2ffa0 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
2ffb0 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
2ffc0 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2ffd0 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
2ffe0 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
2fff0 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
30000 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
30010 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
30020 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
30030 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
30040 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
30050 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
30060 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
30070 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
30080 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
30090 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
300a0 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
300b0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
300c0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
300d0 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
300e0 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
300f0 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
30100 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
30110 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
30120 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
30130 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
30140 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
30150 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
30160 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
30170 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
30180 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
30190 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
301a0 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
301b0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
301c0 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
301d0 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
301e0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
301f0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
30200 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
30210 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
30220 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
30230 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
30240 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
30250 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
30260 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
30270 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
30280 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
30290 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
302a0 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
302b0 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
302c0 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
302d0 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
302e0 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
302f0 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
30300 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
30310 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
30320 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
30330 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
30340 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
30350 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
30360 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
30370 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
30380 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
30390 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
303a0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
303b0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
303c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
303d0 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
303e0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
303f0 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65  * METHOD: sqlite
30400 33 5f 73 74 6d 74 0a 2a 2a 0a 2a 2a 20 41 66 74  3_stmt.**.** Aft
30410 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
30420 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
30430 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
30440 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
30450 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
30460 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
30470 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
30480 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
30490 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
304a0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
304b0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
304c0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
304d0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
304e0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
304f0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
30500 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
30510 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
30520 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
30530 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
30540 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
30550 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
30560 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
30570 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
30580 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
30590 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
305a0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
305b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
305c0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
305d0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
305e0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
305f0 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
30600 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
30610 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
30620 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
30630 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
30640 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
30650 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
30660 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
30670 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
30680 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
30690 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
306a0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
306b0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
306c0 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
306d0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
306e0 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
306f0 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
30700 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
30710 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
30720 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
30730 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
30740 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
30750 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
30760 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
30770 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
30780 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
30790 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
307a0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
307b0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
307c0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
307d0 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
307e0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
307f0 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
30800 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
30810 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
30820 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
30830 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
30840 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
30850 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
30860 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
30870 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
30880 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
30890 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
308a0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
308b0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
308c0 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
308d0 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
308e0 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78   within an.** ex
308f0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
30900 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
30910 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
30920 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
30930 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
30940 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
30950 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
30960 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
30970 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
30980 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
30990 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
309a0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
309b0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
309c0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
309d0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
309e0 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
309f0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
30a00 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
30a10 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
30a20 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
30a30 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
30a40 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
30a50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
30a60 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
30a70 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
30a80 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
30a90 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
30aa0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
30ab0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
30ac0 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
30ad0 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
30ae0 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
30af0 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
30b00 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
30b10 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
30b20 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
30b30 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
30b40 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
30b50 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
30b60 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
30b70 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
30b80 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
30b90 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
30ba0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
30bb0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
30bc0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
30bd0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
30be0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
30bf0 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
30c00 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
30c10 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
30c20 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
30c30 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
30c40 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
30c50 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
30c60 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
30c70 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
30c80 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
30c90 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
30ca0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
30cb0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
30cc0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
30cd0 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
30ce0 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
30cf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
30d00 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
30d10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30d20 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
30d30 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
30d40 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
30d50 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
30d60 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
30d70 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
30d80 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
30d90 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
30da0 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
30db0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
30dc0 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
30dd0 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
30de0 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
30df0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30e00 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
30e10 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
30e20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
30e30 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
30e40 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
30e50 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
30e60 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
30e70 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
30e80 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
30e90 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
30ea0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
30eb0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
30ec0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
30ed0 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
30ee0 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
30ef0 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
30f00 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
30f10 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
30f20 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
30f30 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
30f40 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20  .6.23.1, a call 
30f50 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
30f60 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75  eset()] was requ
30f70 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ired after sqlit
30f80 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
30f90 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f  ed anything.** o
30fa0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
30fb0 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e  E_ROW] before an
30fc0 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
30fd0 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
30fe0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
30ff0 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20  ailure to reset 
31000 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
31010 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a  tement using .**
31020 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31030 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20  )] would result 
31040 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
31050 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
31060 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  m.** sqlite3_ste
31070 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20  p().  But after 
31080 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e  [version 3.6.23.
31090 31 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e  1] ([dateof:3.6.
310a0 32 33 2e 31 5d 2c 0a 2a 2a 20 73 71 6c 69 74 65  23.1],.** sqlite
310b0 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
310c0 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
310d0 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
310e0 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
310f0 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
31100 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
31110 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
31120 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
31130 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
31140 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
31150 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
31160 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
31170 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
31180 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
31190 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
311a0 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
311b0 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
311c0 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
311d0 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
311e0 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
311f0 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
31200 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
31210 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
31220 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
31230 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
31240 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
31250 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
31260 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
31270 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
31280 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
31290 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
312a0 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
312b0 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
312c0 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
312d0 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
312e0 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
312f0 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
31300 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
31310 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
31320 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
31330 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
31340 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
31350 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
31360 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
31370 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
31380 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
31390 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
313a0 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
313b0 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
313c0 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
313d0 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
313e0 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
313f0 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
31400 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
31410 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
31420 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
31430 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
31440 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
31450 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
31460 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
31470 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
31480 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
31490 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
314a0 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
314b0 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
314c0 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
314d0 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
314e0 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
314f0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
31500 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
31510 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
31520 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
31530 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
31540 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
31550 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
31560 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
31570 75 6c 74 20 73 65 74 0a 2a 2a 20 4d 45 54 48 4f  ult set.** METHO
31580 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 0a  D: sqlite3_stmt.
31590 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
315a0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
315b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
315c0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
315d0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
315e0 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
315f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
31600 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
31610 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
31620 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
31630 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
31640 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
31650 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
31660 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
31670 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
31680 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
31690 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
316a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
316b0 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
316c0 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
316d0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
316e0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
316f0 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
31700 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
31710 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
31720 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
31730 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
31740 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
31750 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
31760 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
31770 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
31780 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
31790 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
317a0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
317b0 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
317c0 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
317d0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
317e0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
317f0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
31800 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
31810 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
31820 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
31830 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
31840 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
31850 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
31860 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
31870 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
31880 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
31890 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
318a0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
318b0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
318c0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
318d0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
318e0 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69  _data_count(sqli
318f0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
31900 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31910 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44  F: Fundamental D
31920 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57  atatypes.** KEYW
31930 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58  ORDS: SQLITE_TEX
31940 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20  T.**.** ^(Every 
31950 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20  value in SQLite 
31960 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20  has one of five 
31970 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61  fundamental data
31980 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  types:.**.** <ul
31990 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  >.** <li> 64-bit
319a0 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
319b0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49  ** <li> 64-bit I
319c0 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  EEE floating poi
319d0 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69  nt number.** <li
319e0 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e  > string.** <li>
319f0 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55   BLOB.** <li> NU
31a00 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  LL.** </ul>)^.**
31a10 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
31a20 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f  nts are codes fo
31a30 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20  r each of those 
31a40 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  types..**.** Not
31a50 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49 54  e that the SQLIT
31a60 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20  E_TEXT constant 
31a70 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e  was also used in
31a80 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
31a90 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c  2.** for a compl
31aa0 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20  etely different 
31ab0 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61  meaning.  Softwa
31ac0 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67  re that links ag
31ad0 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51  ainst both.** SQ
31ae0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61  Lite version 2 a
31af0 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  nd SQLite versio
31b00 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53  n 3 should use S
31b10 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74  QLITE3_TEXT, not
31b20 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e  .** SQLITE_TEXT.
31b30 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
31b40 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64  TE_INTEGER  1.#d
31b50 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f  efine SQLITE_FLO
31b60 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20  AT    2.#define 
31b70 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20  SQLITE_BLOB     
31b80 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
31b90 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64  _NULL     5.#ifd
31ba0 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
31bb0 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45   undef SQLITE_TE
31bc0 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  XT.#else.# defin
31bd0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20  e SQLITE_TEXT   
31be0 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69    3.#endif.#defi
31bf0 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20  ne SQLITE3_TEXT 
31c00 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      3../*.** CAP
31c10 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61  I3REF: Result Va
31c20 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72  lues From A Quer
31c30 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  y.** KEYWORDS: {
31c40 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
31c50 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48  nctions}.** METH
31c60 4f 44 3a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  OD: sqlite3_stmt
31c70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
31c80 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
31c90 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
31ca0 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
31cb0 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
31cc0 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
31cd0 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
31ce0 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
31cf0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
31d00 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
31d10 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
31d20 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
31d30 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
31d40 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
31d50 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
31d60 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
31d70 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
31d80 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
31d90 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
31da0 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
31db0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
31dc0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
31dd0 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
31de0 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
31df0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
31e00 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
31e10 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
31e20 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
31e30 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
31e40 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
31e50 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
31e60 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
31e70 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
31e80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
31e90 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
31ea0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
31eb0 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
31ec0 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
31ed0 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
31ee0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
31ef0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
31f00 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
31f10 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
31f20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
31f30 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
31f40 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
31f50 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
31f60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
31f70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
31f80 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
31f90 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
31fa0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
31fb0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
31fc0 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
31fd0 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
31fe0 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
31ff0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
32000 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
32010 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
32020 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
32030 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
32040 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
32050 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
32060 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
32070 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
32080 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
32090 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
320a0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
320b0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
320c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
320d0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
320e0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
320f0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
32100 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
32110 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
32120 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
32130 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
32140 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
32150 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
32160 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32170 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
32180 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
32190 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
321a0 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
321b0 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
321c0 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
321d0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
321e0 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
321f0 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
32200 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
32210 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
32220 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
32230 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
32240 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
32250 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
32260 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
32270 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
32280 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
32290 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
322a0 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
322b0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
322c0 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
322d0 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
322e0 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
322f0 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
32300 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
32310 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32320 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
32330 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
32340 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
32350 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
32360 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
32370 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
32380 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
32390 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
323a0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
323b0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
323c0 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
323d0 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
323e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
323f0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
32400 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
32410 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
32420 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
32430 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
32440 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
32450 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
32460 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32470 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
32480 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
32490 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
324a0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
324b0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
324c0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
324d0 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
324e0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
324f0 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
32500 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
32510 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
32520 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
32530 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
32540 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
32550 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
32560 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
32570 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
32580 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
32590 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
325a0 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
325b0 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
325c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
325d0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
325e0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
325f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32600 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
32610 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
32620 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
32630 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
32640 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
32650 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
32660 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
32670 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
32680 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
32690 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
326a0 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
326b0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
326c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
326d0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
326e0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
326f0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
32700 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
32710 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
32720 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
32730 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
32740 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
32750 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
32760 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
32770 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
32780 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
32790 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
327a0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
327b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
327c0 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
327d0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
327e0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
327f0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
32800 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
32810 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
32820 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
32830 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
32840 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
32850 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
32860 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
32870 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
32880 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
32890 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
328a0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
328b0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
328c0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
328d0 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
328e0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
328f0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
32900 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
32910 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
32920 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
32930 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
32940 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
32950 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
32960 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
32970 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
32980 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74  re always zero-t
32990 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
329a0 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
329b0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
329c0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
329d0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
329e0 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
329f0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 57  nter..**.** <b>W
32a00 61 72 6e 69 6e 67 3a 3c 2f 62 3e 20 5e 54 68 65  arning:</b> ^The
32a10 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
32a20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
32a30 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
32a40 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
32a50 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
32a60 5d 20 6f 62 6a 65 63 74 2e 20 20 49 6e 20 61 20  ] object.  In a 
32a70 6d 75 6c 74 69 74 68 72 65 61 64 65 64 20 65 6e  multithreaded en
32a80 76 69 72 6f 6e 6d 65 6e 74 2c 0a 2a 2a 20 61 6e  vironment,.** an
32a90 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
32aa0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
32ab0 74 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  t may only be us
32ac0 65 64 20 73 61 66 65 6c 79 20 77 69 74 68 0a 2a  ed safely with.*
32ad0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
32ae0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
32af0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
32b00 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
32b10 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
32b20 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
32b30 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
32b40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
32b50 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
32b60 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
32b70 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
32b80 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
32b90 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
32ba0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
32bb0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
32bc0 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
32bd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
32be0 74 65 73 28 29 5d 2c 20 74 68 65 20 62 65 68 61  tes()], the beha
32bf0 76 69 6f 72 20 69 73 20 6e 6f 74 20 74 68 72 65  vior is not thre
32c00 61 64 73 61 66 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  adsafe..**.** Th
32c10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
32c20 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
32c30 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
32c40 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
32c50 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
32c60 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
32c70 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
32c80 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
32c90 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
32ca0 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
32cb0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
32cc0 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
32cd0 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
32ce0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
32cf0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
32d00 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
32d10 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
32d20 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
32d30 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
32d40 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
32d50 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
32d60 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
32d70 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
32d80 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
32d90 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
32da0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
32db0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
32dc0 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
32dd0 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
32de0 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
32df0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
32e00 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
32e10 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
32e20 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
32e30 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
32e40 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
32e50 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
32e60 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
32e70 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
32e80 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
32e90 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
32ea0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
32eb0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c  NTEGER  <td>  FL
32ec0 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76  OAT    <td> Conv
32ed0 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72  ert from integer
32ee0 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72   to float.** <tr
32ef0 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
32f00 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
32f10 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
32f20 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65  ng of the intege
32f30 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
32f40 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c  TEGER  <td>   BL
32f50 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20  OB    <td> Same 
32f60 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54  as INTEGER->TEXT
32f70 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
32f80 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OAT   <td> INTEG
32f90 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
32fa0 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
32fb0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
32fc0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
32fd0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
32fe0 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61  ring of the floa
32ff0 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  t.** <tr><td>  F
33000 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c  LOAT   <td>   BL
33010 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  OB    <td> [CAST
33020 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72  ] to BLOB.** <tr
33030 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
33040 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
33050 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54  d> [CAST] to INT
33060 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  EGER.** <tr><td>
33070 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
33080 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43  FLOAT    <td> [C
33090 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20  AST] to REAL.** 
330a0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
330b0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
330c0 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a   <td> No change.
330d0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
330e0 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  B    <td> INTEGE
330f0 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
33100 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
33110 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
33120 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
33130 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45  td> [CAST] to RE
33140 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  AL.** <tr><td>  
33150 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
33160 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
33170 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
33180 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
33190 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
331a0 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
331b0 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
331c0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
331d0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
331e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
331f0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
33200 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
33210 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
33220 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
33230 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
33240 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
33250 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
33260 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
33270 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
33280 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
33290 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
332a0 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
332b0 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
332c0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
332d0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
332e0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
332f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
33300 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
33310 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
33320 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
33330 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
33340 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
33350 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
33360 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
33370 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
33380 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
33390 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
333a0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
333b0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
333c0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
333d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
333e0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
333f0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
33400 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
33410 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
33420 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
33430 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
33440 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
33450 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
33460 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
33470 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
33480 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
33490 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
334a0 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
334b0 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
334c0 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
334d0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
334e0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
334f0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
33500 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
33510 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
33520 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
33530 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
33540 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
33550 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
33560 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
33570 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
33580 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
33590 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
335a0 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
335b0 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
335c0 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
335d0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
335e0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
335f0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
33600 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
33610 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
33620 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
33630 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
33640 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
33650 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
33660 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e   policy is to in
33670 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69  voke these routi
33680 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66  nes.** in one of
33690 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77   the following w
336a0 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ays:.**.** <ul>.
336b0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
336c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f  column_text() fo
336d0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
336e0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
336f0 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
33700 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
33710 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  b() followed by 
33720 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33730 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
33740 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
33750 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c  mn_text16() foll
33760 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
33770 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
33780 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
33790 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  *.** In other wo
337a0 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20  rds, you should 
337b0 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  call sqlite3_col
337c0 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73  umn_text(),.** s
337d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
337e0 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  ob(), or sqlite3
337f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
33800 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20   first to force 
33810 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  the result.** in
33820 74 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66  to the desired f
33830 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f  ormat, then invo
33840 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ke sqlite3_colum
33850 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20  n_bytes() or.** 
33860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
33870 79 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64  ytes16() to find
33880 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
33890 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74   result.  Do not
338a0 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f   mix calls.** to
338b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
338c0 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
338d0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
338e0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  with calls to.**
338f0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
33900 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64  bytes16(), and d
33910 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20  o not mix calls 
33920 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
33930 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69  n_text16().** wi
33940 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  th calls to sqli
33950 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
33960 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70  ()..**.** ^The p
33970 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
33980 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c   are valid until
33990 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
339a0 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20  on occurs as.** 
339b0 64 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c  described above,
339c0 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74   or until [sqlit
339d0 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
339e0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
339f0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
33a00 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61  inalize()] is ca
33a10 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f  lled.  ^The memo
33a20 72 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f  ry space used to
33a30 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a   hold strings.**
33a40 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72   and BLOBs is fr
33a50 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  eed automaticall
33a60 79 2e 20 20 44 6f 20 3c 65 6d 3e 6e 6f 74 3c 2f  y.  Do <em>not</
33a70 65 6d 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  em> pass the poi
33a80 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
33a90 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
33aa0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
33ab0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
33ac0 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
33ad0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
33ae0 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
33af0 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
33b00 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
33b10 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
33b20 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
33b30 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
33b40 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
33b50 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
33b60 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
33b70 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
33b80 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
33b90 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
33ba0 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
33bb0 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
33bc0 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
33bd0 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
33be0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
33bf0 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
33c00 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
33c10 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ^.*/.const void 
33c20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
33c30 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
33c40 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
33c50 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
33c60 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  n_bytes(sqlite3_
33c70 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
33c80 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
33c90 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
33ca0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
33cb0 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71  iCol);.double sq
33cc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75  lite3_column_dou
33cd0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
33ce0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
33cf0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
33d00 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
33d10 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73  t*, int iCol);.s
33d20 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
33d30 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36  ite3_column_int6
33d40 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
33d50 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
33d60 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
33d70 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
33d80 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
33d90 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
33da0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
33db0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
33dc0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33dd0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
33de0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
33df0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
33e00 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c  , int iCol);.sql
33e10 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69  ite3_value *sqli
33e20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
33e30 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
33e40 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a  int iCol);../*.*
33e50 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74  * CAPI3REF: Dest
33e60 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53  roy A Prepared S
33e70 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
33e80 2a 2a 20 44 45 53 54 52 55 43 54 4f 52 3a 20 73  ** DESTRUCTOR: s
33e90 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
33ea0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
33eb0 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
33ec0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
33ed0 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
33ee0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
33ef0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
33f00 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
33f10 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
33f20 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
33f30 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66   errors.** or if
33f40 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
33f50 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61  s never been eva
33f60 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c  luated, then sql
33f70 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
33f80 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54  returns.** SQLIT
33f90 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d  E_OK.  ^If the m
33fa0 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
33fb0 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65  ation of stateme
33fc0 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65  nt S failed, the
33fd0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e  n.** sqlite3_fin
33fe0 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73  alize(S) returns
33ff0 20 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65   the appropriate
34000 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72   [error code] or
34010 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72  .** [extended er
34020 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
34030 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
34040 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e  nalize(S) routin
34050 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
34060 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72  at any point dur
34070 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20  ing.** the life 
34080 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72  cycle of [prepar
34090 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a  ed statement] S:
340a0 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65  .** before state
340b0 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65  ment S is ever e
340c0 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a  valuated, after.
340d0 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63  ** one or more c
340e0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
340f0 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66  _reset()], or af
34100 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20  ter any call.** 
34110 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
34120 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f  ()] regardless o
34130 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
34140 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
34150 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20  as.** completed 
34160 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  execution..**.**
34170 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74   ^Invoking sqlit
34180 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e  e3_finalize() on
34190 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
341a0 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
341b0 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  -op..**.** The a
341c0 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
341d0 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b  finalize every [
341e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
341f0 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  nt] in order to 
34200 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63  avoid.** resourc
34210 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20  e leaks.  It is 
34220 61 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72  a grievous error
34230 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
34240 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75  tion to try to u
34250 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64  se.** a prepared
34260 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
34270 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
34280 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65  alized.  Any use
34290 20 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a   of a prepared.*
342a0 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65  * statement afte
342b0 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69  r it has been fi
342c0 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75  nalized can resu
342d0 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
342e0 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62  and.** undesirab
342f0 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68  le behavior such
34300 20 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e   as segfaults an
34310 64 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f  d heap corruptio
34320 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  n..*/.int sqlite
34330 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
34340 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
34350 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34360 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
34370 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
34380 65 63 74 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ect.** METHOD: s
34390 71 6c 69 74 65 33 5f 73 74 6d 74 0a 2a 2a 0a 2a  qlite3_stmt.**.*
343a0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
343b0 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
343c0 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
343d0 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
343e0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
343f0 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
34400 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
34410 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
34420 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
34430 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
34440 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
34450 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
34460 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
34470 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
34480 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
34490 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
344a0 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
344b0 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
344c0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
344d0 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
344e0 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
344f0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
34500 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
34510 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
34520 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
34530 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
34540 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
34550 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
34560 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
34570 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
34580 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
34590 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
345a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
345b0 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
345c0 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
345d0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
345e0 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
345f0 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
34600 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
34610 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
34620 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
34630 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
34640 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
34650 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
34660 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
34670 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
34680 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
34690 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
346a0 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
346b0 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
346c0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
346d0 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
346e0 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
346f0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
34700 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
34710 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
34720 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
34730 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
34740 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
34750 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
34760 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
34770 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
34780 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
34790 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
347a0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
347b0 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
347c0 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
347d0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
347e0 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
347f0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
34800 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
34810 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
34820 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
34830 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
34840 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
34850 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
34860 6f 6e 73 7d 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20  ons}.** METHOD: 
34870 73 71 6c 69 74 65 33 0a 2a 2a 0a 2a 2a 20 5e 54  sqlite3.**.** ^T
34880 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
34890 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
348a0 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
348b0 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
348c0 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
348d0 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
348e0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
348f0 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
34900 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
34910 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
34920 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
34930 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
34940 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
34950 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
34960 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
34970 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
34980 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
34990 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
349a0 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
349b0 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
349c0 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
349d0 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
349e0 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
349f0 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
34a00 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
34a10 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
34a20 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
34a30 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
34a40 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
34a50 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34a60 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
34a70 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
34a80 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
34a90 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
34aa0 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
34ab0 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
34ac0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
34ad0 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
34ae0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
34af0 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
34b00 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
34b10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34b20 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
34b30 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
34b40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
34b50 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
34b60 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
34b70 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
34b80 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
34b90 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
34ba0 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
34bb0 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
34bc0 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
34bd0 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
34be0 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
34bf0 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
34c00 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
34c10 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
34c20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
34c30 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
34c40 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
34c50 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
34c60 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
34c70 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
34c80 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
34c90 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
34ca0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
34cb0 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
34cc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
34cd0 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
34ce0 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
34cf0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
34d00 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
34d10 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
34d20 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
34d30 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
34d40 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
34d50 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
34d60 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
34d70 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
34d80 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
34d90 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
34da0 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
34db0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
34dc0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
34dd0 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
34de0 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
34df0 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
34e00 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
34e10 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
34e20 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
34e30 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
34e40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
34e50 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
34e60 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
34e70 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
34e80 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
34e90 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
34ea0 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
34eb0 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
34ec0 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70  meters.  The app
34ed0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
34ee0 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74  set this paramet
34ef0 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45  er to.** [SQLITE
34f00 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65  _UTF16LE] if the
34f10 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
34f20 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
34f30 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61   .** [sqlite3_va
34f40 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20  lue_text16le()] 
34f50 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20  on an input, or 
34f60 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
34f70 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   if the.** imple
34f80 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
34f90 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  s [sqlite3_value
34fa0 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20  _text16be()] on 
34fb0 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20  an input, or.** 
34fc0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69  [SQLITE_UTF16] i
34fd0 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
34fe0 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73  _text16()] is us
34ff0 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  ed, or [SQLITE_U
35000 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73  TF8].** otherwis
35010 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51  e.  ^The same SQ
35020 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62  L function may b
35030 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c  e registered mul
35040 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e  tiple times usin
35050 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70  g.** different p
35060 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
35070 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69  codings, with di
35080 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  fferent implemen
35090 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65  tations for.** e
350a0 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ach encoding..**
350b0 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
350c0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
350d0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
350e0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
350f0 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
35100 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
35110 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
35120 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
35130 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
35140 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  n..**.** ^The fo
35150 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d  urth parameter m
35160 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65  ay optionally be
35170 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49   ORed with [SQLI
35180 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
35190 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74  ].** to signal t
351a0 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hat the function
351b0 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74   will always ret
351c0 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73  urn the same res
351d0 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65  ult given.** the
351e0 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74   same inputs wit
351f0 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  hin a single SQL
35200 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73   statement.  Mos
35210 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
35220 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69  are.** determini
35230 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74  stic.  The built
35240 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53  -in [random()] S
35250 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61  QL function is a
35260 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a  n example of a.*
35270 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  * function that 
35280 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69  is not determini
35290 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74  stic.  The SQLit
352a0 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20  e query planner 
352b0 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65  is able to.** pe
352c0 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c  rform additional
352d0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f   optimizations o
352e0 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20  n deterministic 
352f0 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73  functions, so us
35300 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c  e.** of the [SQL
35310 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
35320 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d  C] flag is recom
35330 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73  mended where pos
35340 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  sible..**.** ^(T
35350 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
35360 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
35370 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  ry pointer.  The
35380 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35390 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  of the.** functi
353a0 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65  on can gain acce
353b0 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74  ss to this point
353c0 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  er using [sqlite
353d0 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29  3_user_data()].)
353e0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78  ^.**.** ^The six
353f0 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20  th, seventh and 
35400 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72  eighth parameter
35410 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20  s, xFunc, xStep 
35420 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a  and xFinal, are.
35430 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43  ** pointers to C
35440 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69  -language functi
35450 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ons that impleme
35460 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
35470 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
35480 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53  ate. ^A scalar S
35490 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
354a0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
354b0 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46  tation of the xF
354c0 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  unc.** callback 
354d0 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74  only; NULL point
354e0 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73  ers must be pass
354f0 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20  ed as the xStep 
35500 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61  and xFinal.** pa
35510 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67  rameters. ^An ag
35520 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63  gregate SQL func
35530 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
35540 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35550 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20  of xStep.** and 
35560 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20  xFinal and NULL 
35570 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20  pointer must be 
35580 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63  passed for xFunc
35590 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20  . ^To delete an 
355a0 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20  existing.** SQL 
355b0 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72  function or aggr
355c0 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c  egate, pass NULL
355d0 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c   pointers for al
355e0 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e  l three function
355f0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a  .** callbacks..*
35600 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69  *.** ^(If the ni
35610 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nth parameter to
35620 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
35630 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73  function_v2() is
35640 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68   not NULL,.** th
35650 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63  en it is destruc
35660 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  tor for the appl
35670 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
35680 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65  nter. .** The de
35690 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f  structor is invo
356a0 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e  ked when the fun
356b0 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64  ction is deleted
356c0 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e  , either by bein
356d0 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20  g.** overloaded 
356e0 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61  or when the data
356f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
35700 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68  closes.)^.** ^Th
35710 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
35720 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20  also invoked if 
35730 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  the call to.** s
35740 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35750 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c  nction_v2() fail
35760 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  s..** ^When the 
35770 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
35780 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68  ack of the tenth
35790 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e   parameter is in
357a0 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20  voked, it.** is 
357b0 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20  passed a single 
357c0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
357d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
357e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
357f0 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69   .** pointer whi
35800 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68  ch was the fifth
35810 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
35820 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
35830 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  ction_v2()..**.*
35840 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74  * ^It is permitt
35850 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d  ed to register m
35860 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e  ultiple implemen
35870 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  tations of the s
35880 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73  ame.** functions
35890 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e   with the same n
358a0 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74  ame but with eit
358b0 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75  her differing nu
358c0 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75  mbers of.** argu
358d0 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69  ments or differi
358e0 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78  ng preferred tex
358f0 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53  t encodings.  ^S
35900 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
35910 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  * the implementa
35920 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63  tion that most c
35930 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74  losely matches t
35940 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20  he way in which 
35950 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  the.** SQL funct
35960 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41  ion is used.  ^A
35970 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
35980 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20  entation with a 
35990 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20  non-negative.** 
359a0 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69  nArg parameter i
359b0 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68  s a better match
359c0 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
359d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
359e0 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69  with.** a negati
359f0 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e  ve nArg.  ^A fun
35a00 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
35a10 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
35a20 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68  ncoding.** match
35a30 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
35a40 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65  encoding is a be
35a50 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68  tter.** match th
35a60 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
35a70 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
35a80 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20   is different.  
35a90 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20  .** ^A function 
35aa0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
35ab0 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73  ng difference is
35ac0 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65   between UTF16le
35ad0 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20   and UTF16be.** 
35ae0 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63  is a closer matc
35af0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
35b00 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
35b10 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
35b20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54  is.** between UT
35b30 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a  F8 and UTF16..**
35b40 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75  .** ^Built-in fu
35b50 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f  nctions may be o
35b60 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77  verloaded by new
35b70 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35b80 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a  ined functions..
35b90 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63  **.** ^An applic
35ba0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35bb0 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  nction is permit
35bc0 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65  ted to call othe
35bd0 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  r.** SQLite inte
35be0 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72  rfaces.  However
35bf0 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73  , such calls mus
35c00 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74  t not.** close t
35c10 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
35c20 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c  ection nor final
35c30 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65  ize or reset the
35c40 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
35c50 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20  tement in which 
35c60 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
35c70 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20  running..*/.int 
35c80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35c90 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
35ca0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
35cb0 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
35cc0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
35cd0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
35ce0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
35cf0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
35d00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35d10 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
35d20 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
35d30 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
35d40 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
35d50 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
35d60 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
35d70 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
35d80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
35d90 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
35da0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
35db0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
35dc0 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
35dd0 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
35de0 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
35df0 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
35e00 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
35e10 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
35e20 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
35e30 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
35e40 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35e50 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
35e60 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
35e70 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
35e80 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20  ontext*).);.int 
35e90 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
35ea0 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
35eb0 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
35ec0 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
35ed0 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
35ee0 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
35ef0 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
35f00 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
35f10 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
35f20 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
35f30 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
35f40 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
35f50 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
35f60 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
35f70 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
35f80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35f90 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
35fa0 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
35fb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35fc0 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
35fd0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
35fe0 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
35ff0 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
36000 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
36010 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
36020 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
36030 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
36040 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
36050 46 38 20 20 20 20 20 20 20 20 20 20 20 31 20 20  F8           1  
36060 20 20 2f 2a 20 49 4d 50 3a 20 52 2d 33 37 35 31    /* IMP: R-3751
36070 34 2d 33 35 35 36 36 20 2a 2f 0a 23 64 65 66 69  4-35566 */.#defi
36080 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  ne SQLITE_UTF16L
36090 45 20 20 20 20 20 20 20 20 32 20 20 20 20 2f 2a  E        2    /*
360a0 20 49 4d 50 3a 20 52 2d 30 33 33 37 31 2d 33 37   IMP: R-03371-37
360b0 36 33 37 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  637 */.#define S
360c0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
360d0 20 20 20 20 20 33 20 20 20 20 2f 2a 20 49 4d 50       3    /* IMP
360e0 3a 20 52 2d 35 31 39 37 31 2d 33 34 31 35 34 20  : R-51971-34154 
360f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
36100 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
36110 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
36120 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
36130 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
36140 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
36150 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74  5    /* Deprecat
36160 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
36170 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
36180 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
36190 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
361a0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
361b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
361c0 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a  nction Flags.**.
361d0 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
361e0 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74  ts may be ORed t
361f0 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65  ogether with the
36200 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
36210 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65  8 | preferred te
36220 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20  xt encoding] as 
36230 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
36240 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ent.** to [sqlit
36250 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
36260 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
36270 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
36280 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
36290 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
362a0 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23  tion_v2()]..*/.#
362b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
362c0 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30  TERMINISTIC    0
362d0 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x800../*.** CAPI
362e0 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
362f0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
36300 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
36310 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
36320 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
36330 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
36340 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
36350 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
36360 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
36370 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
36380 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
36390 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
363a0 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
363b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
363c0 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
363d0 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
363e0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 65 6e 63 6f  ctions.  To enco
363f0 75 72 61 67 65 20 70 72 6f 67 72 61 6d 6d 65 72  urage programmer
36400 73 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68  s to avoid.** th
36410 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77  ese functions, w
36420 65 20 77 69 6c 6c 20 6e 6f 74 20 65 78 70 6c 61  e will not expla
36430 69 6e 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  in what they do.
36440 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
36450 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
36460 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
36470 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
36480 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
36490 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
364a0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
364b0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
364c0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
364d0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
364e0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
364f0 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
36500 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
36510 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
36520 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
36530 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
36540 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
36550 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
36560 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
36570 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
36580 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
36590 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
365a0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
365b0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
365c0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
365d0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20  e3_int64,int),. 
365e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
365f0 20 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74       void*,sqlit
36600 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
36610 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
36620 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
36630 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48 4f   Values.** METHO
36640 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  D: sqlite3_value
36650 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
36660 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
36670 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
36680 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
36690 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
366a0 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
366b0 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
366c0 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
366d0 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
366e0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
366f0 20 61 67 67 72 65 67 61 74 65 2e 20 20 0a 2a 2a   aggregate.  .**
36700 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
36710 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
36720 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
36730 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
36740 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
36750 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36760 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
36770 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
36780 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
36790 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
367a0 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
367b0 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
367c0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
367d0 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
367e0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
367f0 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
36800 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
36810 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
36820 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
36830 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
36840 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
36850 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36860 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
36870 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
36880 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
36890 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
368a0 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
368b0 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
368c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
368d0 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
368e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
368f0 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
36900 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
36910 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36920 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
36930 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
36940 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
36950 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
36960 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
36970 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
36980 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
36990 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
369a0 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
369b0 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
369c0 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
369d0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
369e0 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
369f0 61 74 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  at these routine
36a00 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20  s take a single 
36a10 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
36a20 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
36a30 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74  .** pointer inst
36a40 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65  ead of a [sqlite
36a50 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72  3_stmt*] pointer
36a60 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20   and an integer 
36a70 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a  column number..*
36a80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36a90 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
36aa0 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61   interface extra
36ab0 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72  cts a UTF-16 str
36ac0 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  ing.** in the na
36ad0 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20  tive byte-order 
36ae0 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68  of the host mach
36af0 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ine.  ^The.** sq
36b00 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
36b10 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74  16be() and sqlit
36b20 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
36b30 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  e() interfaces.*
36b40 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36  * extract UTF-16
36b50 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d   strings as big-
36b60 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c  endian and littl
36b70 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74  e-endian respect
36b80 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ively..**.** ^(T
36b90 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
36ba0 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20  _numeric_type() 
36bb0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
36bc0 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e  ts to apply.** n
36bd0 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20  umeric affinity 
36be0 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54  to the value.  T
36bf0 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61  his means that a
36c00 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20  n attempt is.** 
36c10 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20  made to convert 
36c20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20  the value to an 
36c30 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74  integer or float
36c40 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a  ing point.  If.*
36c50 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73  * such a convers
36c60 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20  ion is possible 
36c70 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20  without loss of 
36c80 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20  information (in 
36c90 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20  other.** words, 
36ca0 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20  if the value is 
36cb0 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f  a string that lo
36cc0 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65  oks like a numbe
36cd0 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  r).** then the c
36ce0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72  onversion is per
36cf0 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69  formed.  Otherwi
36d00 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e  se no conversion
36d10 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20   occurs..** The 
36d20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
36d30 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65  | datatype] afte
36d40 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  r conversion is 
36d50 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a  returned.)^.**.*
36d60 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72  * Please pay par
36d70 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f  ticular attentio
36d80 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68  n to the fact th
36d90 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72  at the pointer r
36da0 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
36db0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
36dc0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
36dd0 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20  _value_text()], 
36de0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  or.** [sqlite3_v
36df0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63  alue_text16()] c
36e00 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  an be invalidate
36e10 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e  d by a subsequen
36e20 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
36e30 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
36e40 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  s()], [sqlite3_v
36e50 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c  alue_bytes16()],
36e60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
36e70 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
36e80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
36e90 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  xt16()]..**.** T
36ea0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75  hese routines mu
36eb0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
36ec0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
36ed0 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20  d as.** the SQL 
36ee0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75  function that su
36ef0 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69  pplied the [sqli
36f00 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61  te3_value*] para
36f10 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74  meters..*/.const
36f20 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
36f30 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65  alue_blob(sqlite
36f40 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
36f50 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
36f60 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  es(sqlite3_value
36f70 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
36f80 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71  value_bytes16(sq
36f90 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64  lite3_value*);.d
36fa0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61  ouble sqlite3_va
36fb0 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  lue_double(sqlit
36fc0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
36fd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
36fe0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
36ff0 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
37000 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69   sqlite3_value_i
37010 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c  nt64(sqlite3_val
37020 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69  ue*);.const unsi
37030 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
37040 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
37050 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
37060 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
37070 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
37080 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37090 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
370a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
370b0 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  6le(sqlite3_valu
370c0 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  e*);.const void 
370d0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
370e0 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
370f0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
37100 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
37110 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37120 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
37130 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
37140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
37150 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37160 3a 20 46 69 6e 64 69 6e 67 20 54 68 65 20 53 75  : Finding The Su
37170 62 74 79 70 65 20 4f 66 20 53 51 4c 20 56 61 6c  btype Of SQL Val
37180 75 65 73 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73  ues.** METHOD: s
37190 71 6c 69 74 65 33 5f 76 61 6c 75 65 0a 2a 2a 0a  qlite3_value.**.
371a0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 76  ** The sqlite3_v
371b0 61 6c 75 65 5f 73 75 62 74 79 70 65 28 56 29 20  alue_subtype(V) 
371c0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
371d0 20 74 68 65 20 73 75 62 74 79 70 65 20 66 6f 72   the subtype for
371e0 0a 2a 2a 20 61 6e 20 5b 61 70 70 6c 69 63 61 74  .** an [applicat
371f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
37200 66 75 6e 63 74 69 6f 6e 5d 20 61 72 67 75 6d 65  function] argume
37210 6e 74 20 56 2e 20 20 54 68 65 20 73 75 62 74 79  nt V.  The subty
37220 70 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  pe.** informatio
37230 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
37240 20 70 61 73 73 20 61 20 6c 69 6d 69 74 65 64 20   pass a limited 
37250 61 6d 6f 75 6e 74 20 6f 66 20 63 6f 6e 74 65 78  amount of contex
37260 74 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 53 51  t from.** one SQ
37270 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 61 6e  L function to an
37280 6f 74 68 65 72 2e 20 20 55 73 65 20 74 68 65 20  other.  Use the 
37290 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f  [sqlite3_result_
372a0 73 75 62 74 79 70 65 28 29 5d 0a 2a 2a 20 72 6f  subtype()].** ro
372b0 75 74 69 6e 65 20 74 6f 20 73 65 74 20 74 68 65  utine to set the
372c0 20 73 75 62 74 79 70 65 20 66 6f 72 20 74 68 65   subtype for the
372d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
372e0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
372f0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
37300 61 6b 65 73 20 6e 6f 20 75 73 65 20 6f 66 20 73  akes no use of s
37310 75 62 74 79 70 65 20 69 74 73 65 6c 66 2e 20 20  ubtype itself.  
37320 49 74 20 6d 65 72 65 6c 79 20 70 61 73 73 65 73  It merely passes
37330 20 74 68 65 20 73 75 62 74 79 70 65 0a 2a 2a 20   the subtype.** 
37340 66 72 6f 6d 20 74 68 65 20 72 65 73 75 6c 74 20  from the result 
37350 6f 66 20 6f 6e 65 20 5b 61 70 70 6c 69 63 61 74  of one [applicat
37360 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
37370 66 75 6e 63 74 69 6f 6e 5d 20 69 6e 74 6f 20 74  function] into t
37380 68 65 0a 2a 2a 20 69 6e 70 75 74 20 6f 66 20 61  he.** input of a
37390 6e 6f 74 68 65 72 2e 0a 2a 2f 0a 75 6e 73 69 67  nother..*/.unsig
373a0 6e 65 64 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  ned int sqlite3_
373b0 76 61 6c 75 65 5f 73 75 62 74 79 70 65 28 73 71  value_subtype(sq
373c0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
373d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
373e0 43 6f 70 79 20 41 6e 64 20 46 72 65 65 20 53 51  Copy And Free SQ
373f0 4c 20 56 61 6c 75 65 73 0a 2a 2a 20 4d 45 54 48  L Values.** METH
37400 4f 44 3a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  OD: sqlite3_valu
37410 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
37420 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70 28 56  ite3_value_dup(V
37430 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
37440 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
37450 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
37460 2a 2a 20 6f 62 6a 65 63 74 20 44 20 61 6e 64 20  ** object D and 
37470 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
37480 72 20 74 6f 20 74 68 61 74 20 63 6f 70 79 2e 20  r to that copy. 
37490 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76   ^The [sqlite3_v
374a0 61 6c 75 65 5d 20 72 65 74 75 72 6e 65 64 0a 2a  alue] returned.*
374b0 2a 20 69 73 20 61 20 5b 70 72 6f 74 65 63 74 65  * is a [protecte
374c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
374d0 20 6f 62 6a 65 63 74 20 65 76 65 6e 20 69 66 20   object even if 
374e0 74 68 65 20 69 6e 70 75 74 20 69 73 20 6e 6f 74  the input is not
374f0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
37500 33 5f 76 61 6c 75 65 5f 64 75 70 28 56 29 20 69  3_value_dup(V) i
37510 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
37520 20 4e 55 4c 4c 20 69 66 20 56 20 69 73 20 4e 55   NULL if V is NU
37530 4c 4c 20 6f 72 20 69 66 20 61 0a 2a 2a 20 6d 65  LL or if a.** me
37540 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
37550 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fails..**.** ^Th
37560 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
37570 66 72 65 65 28 56 29 20 69 6e 74 65 72 66 61 63  free(V) interfac
37580 65 20 66 72 65 65 73 20 61 6e 20 5b 73 71 6c 69  e frees an [sqli
37590 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
375a0 74 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  t.** previously 
375b0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
375c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 75 70  qlite3_value_dup
375d0 28 29 5d 2e 20 20 5e 49 66 20 56 20 69 73 20 61  ()].  ^If V is a
375e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
375f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 76 61   then sqlite3_va
37600 6c 75 65 5f 66 72 65 65 28 56 29 20 69 73 20 61  lue_free(V) is a
37610 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
37620 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75  .*/.sqlite3_valu
37630 65 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e *sqlite3_value
37640 5f 64 75 70 28 63 6f 6e 73 74 20 73 71 6c 69 74  _dup(const sqlit
37650 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f 69 64  e3_value*);.void
37660 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 66   sqlite3_value_f
37670 72 65 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ree(sqlite3_valu
37680 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  e*);../*.** CAPI
37690 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67  3REF: Obtain Agg
376a0 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20  regate Function 
376b0 43 6f 6e 74 65 78 74 0a 2a 2a 20 4d 45 54 48 4f  Context.** METHO
376c0 44 3a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  D: sqlite3_conte
376d0 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
376e0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
376f0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
37700 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
37710 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
37720 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
37730 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
37740 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
37750 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
37760 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
37770 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
37780 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
37790 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
377a0 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
377b0 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
377c0 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
377d0 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
377e0 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
377f0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
37800 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
37810 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
37820 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
37830 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
37840 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
37850 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
37860 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
37870 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
37880 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
37890 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
378a0 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
378b0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
378c0 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
378d0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
378e0 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
378f0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
37900 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
37910 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
37920 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
37930 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
37940 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
37950 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
37960 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
37970 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
37980 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
37990 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
379a0 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
379b0 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
379c0 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
379d0 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
379e0 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
379f0 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
37a00 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
37a10 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
37a20 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
37a30 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
37a40 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
37a50 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
37a60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
37a70 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
37a80 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
37a90 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
37aa0 65 72 20 0a 2a 2a 20 77 68 65 6e 20 66 69 72 73  er .** when firs
37ab0 74 20 63 61 6c 6c 65 64 20 69 66 20 4e 20 69 73  t called if N is
37ac0 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
37ad0 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
37ae0 66 20 61 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  f a memory.** al
37af0 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
37b00 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
37b10 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
37b20 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
37b30 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
37b40 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
37b50 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
37b60 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
37b70 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
37b80 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
37b90 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
37ba0 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
37bb0 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
37bc0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
37bd0 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
37be0 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
37bf0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
37c00 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
37c10 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
37c20 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
37c30 2e 29 5e 20 20 57 69 74 68 69 6e 20 74 68 65 20  .)^  Within the 
37c40 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 2c  xFinal callback,
37c50 20 69 74 20 69 73 20 63 75 73 74 6f 6d 61 72 79   it is customary
37c60 20 74 6f 20 73 65 74 0a 2a 2a 20 4e 3d 30 20 69   to set.** N=0 i
37c70 6e 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  n calls to sqlit
37c80 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37c90 74 65 78 74 28 43 2c 4e 29 20 73 6f 20 74 68 61  text(C,N) so tha
37ca0 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69 6e 74 6c 65  t no .** pointle
37cb0 73 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ss memory alloca
37cc0 74 69 6f 6e 73 20 6f 63 63 75 72 2e 0a 2a 2a 0a  tions occur..**.
37cd0 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
37ce0 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
37cf0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
37d00 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
37d10 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
37d20 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
37d30 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
37d40 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
37d50 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
37d60 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
37d70 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
37d80 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
37d90 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
37da0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
37db0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
37dc0 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
37dd0 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
37de0 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
37df0 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
37e00 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
37e10 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
37e20 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
37e30 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
37e40 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
37e50 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
37e60 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
37e70 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
37e80 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
37e90 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
37ea0 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
37eb0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
37ec0 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
37ed0 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
37ee0 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
37ef0 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33   METHOD: sqlite3
37f00 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e  _context.**.** ^
37f10 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72  The sqlite3_user
37f20 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  _data() interfac
37f30 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
37f40 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
37f50 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20  er that was the 
37f60 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65  pUserData parame
37f70 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72  ter (the 5th par
37f80 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
37f90 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
37fa0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
37fb0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
37fc0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
37fd0 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
37fe0 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
37ff0 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
38000 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
38010 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a  d function..**.*
38020 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d  * This routine m
38030 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
38040 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
38050 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74  ad in which.** t
38060 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
38070 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
38080 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
38090 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65  oid *sqlite3_use
380a0 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  r_data(sqlite3_c
380b0 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
380c0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
380d0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46  ase Connection F
380e0 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  or Functions.** 
380f0 4d 45 54 48 4f 44 3a 20 73 71 6c 69 74 65 33 5f  METHOD: sqlite3_
38100 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 5e 54  context.**.** ^T
38110 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
38120 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
38130 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
38140 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
38150 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
38160 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
38170 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
38180 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
38190 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
381a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
381b0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
381c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
381d0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
381e0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
381f0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
38200 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
38210 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
38220 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
38230 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
38240 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
38250 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
38260 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
38270 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
38280 0a 2a 2a 20 4d 45 54 48 4f 44 3a 20 73 71 6c 69  .** METHOD: sqli
38290 74 65 33 5f 63 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  te3_context.**.*
382a0 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
382b0 73 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79  s may be used by
382c0 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61 74 65 29   (non-aggregate)
382d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
382e0 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
382f0 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
38300 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
38310 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
38320 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
38330 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
38340 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
38350 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
38360 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
38370 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
38380 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
38390 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
383a0 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
383b0 20 70 72 65 73 65 72 76 65 64 2e 20 20 41 6e 20   preserved.  An 
383c0 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66 20 77 68  example.** of wh
383d0 65 72 65 20 74 68 69 73 20 6d 69 67 68 74 20 62  ere this might b
383e0 65 20 75 73 65 66 75 6c 20 69 73 20 69 6e 20 61  e useful is in a
383f0 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
38400 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a 2a 2a 20  ion matching.** 
38410 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
38420 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
38430 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
38440 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20  pression can be 
38450 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74  stored as.** met
38460 61 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64  adata associated
38470 20 77 69 74 68 20 74 68 65 20 70 61 74 74 65 72   with the patter
38480 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a 2a 20 54  n string.  .** T
38490 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  hen as long as t
384a0 68 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  he pattern strin
384b0 67 20 72 65 6d 61 69 6e 73 20 74 68 65 20 73 61  g remains the sa
384c0 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f 6d 70 69  me,.** the compi
384d0 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
384e0 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
384f0 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
38500 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
38510 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
38520 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
38530 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
38540 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
38550 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
38560 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
38570 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
38580 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
38590 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
385a0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
385b0 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
385c0 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
385d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
385e0 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 74   function. ^If t
385f0 68 65 72 65 20 69 73 20 6e 6f 20 6d 65 74 61 64  here is no metad
38600 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
38610 64 20 77 69 74 68 20 74 68 65 20 66 75 6e 63 74  d with the funct
38620 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c 20 74 68  ion argument, th
38630 69 73 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  is sqlite3_get_a
38640 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
38650 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ce.** returns a 
38660 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
38670 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
38680 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e  _set_auxdata(C,N
38690 2c 50 2c 58 29 20 69 6e 74 65 72 66 61 63 65 20  ,P,X) interface 
386a0 73 61 76 65 73 20 50 20 61 73 20 6d 65 74 61 64  saves P as metad
386b0 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68  ata for the N-th
386c0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  .** argument of 
386d0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
386e0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
386f0 2e 20 20 5e 53 75 62 73 65 71 75 65 6e 74 0a 2a  .  ^Subsequent.*
38700 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
38710 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 43  e3_get_auxdata(C
38720 2c 4e 29 20 72 65 74 75 72 6e 20 50 20 66 72 6f  ,N) return P fro
38730 6d 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  m the most recen
38740 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  t.** sqlite3_set
38750 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58  _auxdata(C,N,P,X
38760 29 20 63 61 6c 6c 20 69 66 20 74 68 65 20 6d 65  ) call if the me
38770 74 61 64 61 74 61 20 69 73 20 73 74 69 6c 6c 20  tadata is still 
38780 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e 55 4c 4c  valid or.** NULL
38790 20 69 66 20 74 68 65 20 6d 65 74